gtk-doc and preprocessor statements

[Philip Kovacs]

I'm using gtk-doc 1.8.  Am I correct that gtk-doc cannot really
use preprocessor statements to conditionally build certain parts
of the documentation?  I am interested in forms such as this:

.h file:
-------

#ifdef HAVE_FOO
/**
 * Foo:
 * @param1: etc.
 * @param2: etc.
 *
 * Description of Foo.
 **/
typedef void (*FooCallback) (void *param1, void *param2);
#endif

(i.e. where the entire definition is omitted from the docs if HAVE_FOO
 isn't defined).

Phil




_______________________________________________
gtk-doc-list mailing list
gtk-doc-list@...
http://mail.gnome.org/mailman/listinfo/gtk-doc-list

[Damon Chaplin-2]

On Thu, 2007-05-31 at 21:38 -0400, Philip Kovacs wrote:

> I'm using gtk-doc 1.8.  Am I correct that gtk-doc cannot really
> use preprocessor statements to conditionally build certain parts
> of the documentation?  I am interested in forms such as this:
>
> .h file:
> -------
>
> #ifdef HAVE_FOO
> /**
>  * Foo:
>  * @param1: etc.
>  * @param2: etc.
>  *
>  * Description of Foo.
>  **/
> typedef void (*FooCallback) (void *param1, void *param2);
> #endif
>
> (i.e. where the entire definition is omitted from the docs if HAVE_FOO
>  isn't defined).

gtk-doc doesn't do anything like that.

I'm not sure how useful it would be anyway. Wouldn't it be more useful
to include the function in the documentation and say that it is only
available where FOO is installed? Otherwise developers may use the
function and not realise it may not be available everywhere. Or if they
don't have FOO installed they may not know the function is available at
all.

Damon


_______________________________________________
gtk-doc-list mailing list
gtk-doc-list@...
http://mail.gnome.org/mailman/listinfo/gtk-doc-list

[Philip Kovacs]

Damon Chaplin wrote:

> gtk-doc doesn't do anything like that.
>
> I'm not sure how useful it would be anyway. Wouldn't it be more useful
> to include the function in the documentation and say that it is only
> available where FOO is installed? Otherwise developers may use the
> function and not realise it may not be available everywhere. Or if they
> don't have FOO installed they may not know the function is available at
> all.
>
> Damon

Yes, it is probably better to return some error, e.g. a GError "function
not available", back to the
caller of any library function that is not available on the
installation, rather than hiding the function
altogether.

Thanks for your reply.

Phil
_______________________________________________
gtk-doc-list mailing list
gtk-doc-list@...
http://mail.gnome.org/mailman/listinfo/gtk-doc-list

Hi,

I had a look at the sources. I belive gtk-doc is only dealing with  
#ifdef #endif section in the case of deprecated api. beside that its  
skipping them. Passing some defines to handle them would need real #if  
and #ifdef parsing. Have a look at gtkdoc-scan.in.

Stefan

Quoting Philip Kovacs <kovacsp3@...>:

> I'm using gtk-doc 1.8.  Am I correct that gtk-doc cannot really
> use preprocessor statements to conditionally build certain parts
> of the documentation?  I am interested in forms such as this:
>
> .h file:
> -------
>
> #ifdef HAVE_FOO
> /**
>  * Foo:
>  * @param1: etc.
>  * @param2: etc.
>  *
>  * Description of Foo.
>  **/
> typedef void (*FooCallback) (void *param1, void *param2);
> #endif
>
> (i.e. where the entire definition is omitted from the docs if HAVE_FOO
>  isn't defined).
>
> Phil
>
>
>

_______________________________________________
gtk-doc-list mailing list
gtk-doc-list@...
http://mail.gnome.org/mailman/listinfo/gtk-doc-list