Re: Ideas about improving gtk-doc

[Damon Chaplin <damon karuna uklinux net>]

On Thu, 2004-12-16 at 00:15, Brian Cameron wrote:

>Damon suggests that the above changes would not be too hard to
implement.
> Would someone who is familiar with the gtk-doc logic be willing to make
> these changes?  If not, I would appreciate it if someone could highlight
> what code changes will be necessary to implement the logic so I can go
> ahead and do the work.  I'm not familiar with gtk-doc's logic, so an
> overview of how to go about making these sorts of changes would be
> useful.

I guess noone is volunteering, so it's up to you!
(Reviewing patches occasionally is about my limit, I'm afraid.)

I'll try to give hints on what needs changing. Mostly it is in
gtkdoc-mkdb.in:


> 1. Currently the "Deprecated" tag only highlights information about
>     the deprecation, such as:
> 
>      * Deprecated: Use gdk_draw_layout() instead.
> 
>     Changing this to also include information about what version the deprecation
>     happened would be useful.  For example, if a function was deprecated in
>     version 2.6, the tag could look like this:
> 
>      * Deprecated: 2.6: Use gdk_draw_layout() instead.
> 
>     Then the version information could be included along with the descriptive
>     text.  The version information should be optional so gtk-doc still works
>     with comments that do not include this bit of information.

You could change MakeDeprecationNote() in gtkdoc-mkdb.in. You could
parse $Deprecated{$symbol} to get the version number if it is present,
and output some extra text.


> 2. Highlight change to data structures and enumerations:
> 
>     This could be managed by adding Since and Deprecated tags to the
>     structure description as follows:
> 
>      @height:Since 2.6: Type gint: the height of the rectangle.
>      @height:Deprecated 2.6: Type gint: the height of the rectangle.
>      @GDK_WINDOW_FOREIGN: Since 2.6: Type gint: foreign window (see gdk_window_foreign_new())
>      @GDK_WINDOW_FOREIGN: Deprecated 2.6: Type gint: foreign window (see gdk_window_foreign_new())
> 
>     Note that we also added a "Type: <string>" argument so that the datatype
>     for each element can be identified.  This is optional and should really only
>     be used when commenting an element that has been removed from a structure.
>     The datatype should be figured out from the code directly for elements that
>     are still in the data structure.  The "Type" argument is not needed for
>     enumerations since they are all of the same data type.
> 
>     In the generated gtk-docs, additional text highlighting changes would
>     display something like this:
> 
>      enum GtkFooEnum
>      typedef enum
>      {
>         GTK_FOO_VALUE_1
>         GTK_FOO_VALUE_3  (Added 2.6)
>      } GtkFooEnum
> 
>      GTK_FOO_VALUE_2  Removed 2.4

You could change OutputStruct() in gtkdoc-mkdb.in. Near the bottom of
the function it creates the "<variablelist>". You could parse the
$field_descr to get the version number info and output extra text for
it.

Removed elements won't be in $SymbolParams when the docs are in the
tmpl/ files. You may need to tweak ReadTemplateFile() so they get added.


> 3. Add a keyword "Stability" which will be used much like "Since" and "Deprecated".
>     Valid values would be:
> 
>      Stable   - the interface is not going to change until the next major release
>                 (2.0 to 3.0 for example).  It will not change in a minor release
>                 (like 2.2 to 2.6)
>      Unstable - the interface may change in a minor release and should not be
>                 relied upon.
>      Private  - the interface exists only for private use and should not be used
>                 for general consumption.  An example would be a gdk function that
>                 can be used by gtk, but should not be used by any other library.
> 
>     Such stability levels would be displayed along with the function information
>     in the generated gtk-docs.  Over time it might be desirable to add more
>     stability levels to describe interfaces in more level of detail, so it would
>     be nice if this feature were implemented in a way that makes it easy to
>     add additional stability levels.  Alternatively, gtk-doc could simply allow
>     any string to be used as the stability level, so that each project can use
>     whatever keywords make the most sense for that project.
> 
>     There was some question about whether this additional information would be
>     useful, but I think that the discussion on the desktop-devel list highlights
>     that being able to classify interfaces is something that is generally
>     desired.

You can probably copy the code that uses the %Since array for this
pretty much. I guess that "Stable" will be the default and we won't
output anything in that case?


> 4. Add two new types, FILE and ENVVAR, for documenting files and environment
>     variables.  They would also support the "Since" and "Deprecated" tags.
>     They would work much in the same way as ENUM or STRUCT except that they
>     would document a file or environment variable rather than a macro.
>     Files and environment variables are different than other interfaces in the
>     sense that these aren't declared like a macro, enumeration or function.
>     Therefore, users could include documentation comments for these two new
>     types either next to a "#define" which is used to specify the FILE or
>     ENVVAR or above a function that makes use of them.

These will be a bit harder to do. I think it would be easiest to just
support documentation for these within the source code, using a special
"FILE:" and "ENVVAR:" prefix, e.g.

  /**
   * FILE:stdio.h
   *
   * Description of file.
   */ 

In OutputDeclaration() you can check for the special prefixes and call
new functions OutputFile() and OutputEnvVar().


> 5. It would be useful if gtk-docs generated an additional page that highlights
>     all changes that are found in the gtk-docs.  This page would highlight all
>     interfaces (functions, structures, enumerations, files, environment variables)
>     deprecated, added, or changed in all previous releases.  This would serve as a
>     reference page to anyone who is interested in seeing what interfaces have
>     changed from release-to-release.  This would be much like the current index
>     of deprecated symbols except that it would contain details about files,
>     and environment variables.  It would also clearly state which version each
>     symbol was deprecated.  Here's a link to an example of the page that gtk-doc
>     currently can generate:
> 
>      http://developer.gnome.org/doc/API/2.0/gtk/ix02.html

I don't know how to do this one yet. We can come back to it later.

Damon