Re: Ideas about improving gtk-doc
- From: Stefan Kost <kost imn htwk-leipzig de>
- To: Brian Cameron Sun COM
- Cc: gtk-doc-list gnome org, sun-sac-foss-ext Sun COM
- Subject: Re: Ideas about improving gtk-doc
- Date: Thu, 16 Dec 2004 13:42:59 +0100
Hi Brian,
-- snip --
>
> 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.
>
That is a still a problem, as for comment in the source one canot yet tell what
for the comment is. gtk-doc relies on the fact that c symbol names are uniqe (at
least in the context of a file). Therefore it can figue out the type form the
source (wheter it is a enum, a struct or a function).
For FILE and ENVVAR stuff we need to invent some markup that I can tell gtk-doc
what this documentation is about. If we do this I would like to see this done so
that also the short,long descriptions and see also sections can be commented in
the source.
example:
/**
* DISPLAY_ENV_VAR:
*
* Allows to set ...
*/
#define DISPLAY_ENV_VAR="DISPLAY";
that would be included in the docs as a plain define.
Unfortunately the 'ClassName::SignalName' is already used.
So we need either a prefix and a delimiter
* ENVVAR=DISPLAY_ENV_VAR:
* SHORT_DESC=CLASSNAME:
or a new keyword like
* DISPLAY_ENV_VAR:
* Type: Envvar
* Classname:
* Type: ShortDescription
Ciao
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
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]