Re: Ideas about improving gtk-doc

[Damon Chaplin <damon karuna uklinux net>]

On Thu, 2004-12-09 at 23:51, Brian Cameron wrote:

> With that overview, some suggestions about how we could add the needed
> functionality follow:
> 
> 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.

I think the "Deprecated:" tag with the descriptive text is currently
optional. gtk-doc also looks for macros like GTK_DISABLE_DEPRECATED in
the header files, and marks any declarations inside that as deprecated.

So for your change we'd also have to add "Deprecated:" tags to a lot of
deprecated symbols. That isn't a big problem though.


> 2. Highlight change to data structures and enumerations:
> 
>     Perhaps this could be done by adding a new keyword to the list so a new element
>     could be highlighted by:
> 
>     @height:Since 2.6: the height of the rectangle.
>     @height:Removed 2.6: the height of the rectangle.
>     @GDK_WINDOW_FOREIGN: Since 2.6: foreign window (see gdk_window_foreign_new())
>     @GDK_WINDOW_FOREIGN: Removed 2.6: foreign window (see gdk_window_foreign_new())
> 
>     The scripts for checking structures should be smart enough to verify ABI
>     compatibility.  In other words, ABI is only not broken if elements in data
>     structures are added to the end of the structure.  If enumeration values
>     or data structure elements are removed, or if elements in data structures
>     are added in anywhere but the end, this should be highlighted as an ABI
>     breakage.
> 
>     In the generated gtk-docs, additional text highlighting changes would look
>     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
> 
>     Values added to the end of a structure sould be displayed like this:
> 
>     GtkFooStruct
>     typedef struct {
>        gint val1
>        gint val2
>        gint val3  (Added 2.6)
>     }
> 
>     When a structure changes in a way other than an addition to the last element, it
>     should be be displayed like this:
> 
>     GtkFooStruct
>     typedef struct {
>        gint val1
>        gint val3 (Added 2.6)
>     }
> 
>     Stucture 2.6 and earlier:
> 
>     GtkFooStruct
>     typedef struct {
>        gint val1
>        gint val2
>        gint val3  (Added 2.6)
>     }
> 
>     If a structure changes in a way that breaks ABI compatibility, it would be useful
>     if functions that make use of the structure are highlighted as being affected by
>     the breakage.

My only worry here is struct fields and enumeration values that have
been removed. We may still have the description of the field or enum
value, but since it isn't in the C file anymore we don't know what its
type or integer value was. Does that matter for the docs?
If it does, maybe it should be left in the source code but commented
out.


> 3. Add a keyword "Stability" which will be used much like "Since", "Deprecated", etc.
>     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.
>     Obsolete - the interface exists, but should not be used since it is obsolete,
>                typically when the function has been deprecated.
>     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.

I'm not sure we need "Obsolete" when we can already mark the interface
as deprecated. Is there any difference?


> 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.

I would like to see these. I agree with you that we are doing a really
bad job at documenting these types of things at present.


> 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.

Do you mean by using things like the "Since:" and "Deprecated:" tags?
That should be fairly easy.


Overall I'm happy with the proposed changes. They don't look too hard to
implement.

Damon