Re: Ideas about improving gtk-doc

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

Hi Brian,

replying to just that one ...

> Stefan says:
>> The beauty 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)
> 
> I think you are missing something.  The issue is not that environment
> variables
> or file locations could affect the function interfaces (which is true), but
> that environment variables and file locations are interfaces deserving of
> documentation as much as function interfaces.
> 
> Users and developers might be reasonably interested to know what file
> locations
> the code depends upon and how environment variables affect the way the code
> runs.  I think making gtk-doc support the ability to document these
> interfaces
> makes sense, especially since such documentation would really be quite
> similar
> to the way gtk-doc already heandles other interfaces.
> 
> I mean you could make the same argument about macros, enumerations, or
> structures.
> Why document them with gtk-doc when you could just document them
> directly in
> docbook and maintain them that way.  The reason it isn't done that way
> is that
> it is easier to document with standardized comments in the code.  Why
> not support
> such easy documentation for interfaces such as file locations and
> environment
> variables?  Adding such functionality seems fairly straightforward since
> gtk-doc
> already supports documenting many different types of interfaces already.
> 
What I wonder is where you would like to document such interfaces.
Variables, Structs, Enums are declared/defined somewhere and that makes a good
location to document them as well (even though that is not required, the docs
could appear somewhere else). Environment Variables and Files are just used.
I my packages I do defines for things like configuration filenames, env-variable
names and even URIs (e.g. XML namespace URI(). I can then document the defines
and the code looks even nioce and is easier to maintain. Of course the semantic
of what the define describe is only includes informally, so whe can generate a
list of filenames.

Stefan
-- 
      \|/            Stefan Kost
     <@ @>           private            business
+-oOO-(_)-OOo------------------------------------------------------ - - -  -   -
|       __  Address  Simildenstr. 5     HTWK Leipzig, Fb IMN, Postfach 301166
|      ///           04277 Leipzig      04251 Leipzig
| __  ///            Germany            Germany
| \\\///    Phone    +49341 2253538     +49341 30766101
|  \__/     EMail    st_kost_at_gmx.net kost_at_imn.htwk-leipzig.de
|           WWW      www.sonicpulse.de  www.imn.htwk-leipzig.de/~kost/about.html
===-=-=--=---=---------------------------------- - - -  -    -

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