Re: Ideas about improving gtk-doc

[Brian Cameron <Brian Cameron Sun COM>]

Stefan:

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

I think the cleanest way is to use #define to specify the name of the interface
and document it with the #define.  Though, if an environment variable or file
is used in a very localised piece of code, it could also be documented near the
function that makes use of them.

--

Brian