Re: Ideas about improving gtk-doc

[Stefan Kost <kost imn htwk-leipzig de>]

Hi Brian,

basicaly I agree a lot with matthias' comments.
<snip>
> 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 am neither see much advantage of it. You can still just add this information
if you want. As a developer I will continuosly upgrade to newer version of the
underlying list. Thus when I spot depecated things I will migrate the code.
Afterward it doesn't matter if it is deprecated since 2.0 or 2.2 ...

> 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.
ABI checking is really not what gtk-doc should be concerned with. Apart I
understand that it might be usefull to support "Since:" and "Deprecated:" for
members as well.

> 
> 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.
The problem here is who is the audioence of the docs. The public docs should
only contain public API. I do document private methods in the same fashion as
public API, but that docs is never extracted (unfortunately gtk-doc warns about
that). These comments are purly for the package developers. It might be handy to
build docs for them too.
'Obsolete' is the same as 'Deprecated' for me. And 'Stable' vs.'Unstable' is
often just handled via package versioning.

> 
> 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.
> 
The beaty of the gtk-doc approach is that it mearges with normal docbook
documents. So you can include such list as separate section (you could even
generate those with little tools).
Generally it is true that the behaviour of a method could be affected by
external entities, such as files, environment vars, databases, network
conections, ..., but that sould be informally documented (too much variety).

Ciao
  Stefan
-- 
http://www.buzztard.org

begin:vcard
fn:Stefan Kost
n:Kost;Stefan
org:HTWK Leipzig;FB. IMN
adr:;;Postfach 301166;Leipzig;;04251;Germany
email;internet:kost imn htwk-leipzig de
title:Dipl. Informatiker
tel;work:+49341 30766440
tel;home:+49341 2253538
tel;cell:+49178 3183742
x-mozilla-html:FALSE
url:http://www.imn.htwk-leipzig.de/~kost/about.html
version:2.1
end:vcard