Re: docbook markup in inline docs
- From: Owen Taylor <otaylor redhat com>
- To: "Matthias Clasen" <matthiasc poet de>
- Cc: "Damon Chaplin" <damon ximian com>, <gtk-doc-list gnome org>
- Subject: Re: docbook markup in inline docs
- Date: 18 Oct 2001 11:25:57 -0400
"Matthias Clasen" <matthiasc poet de> writes:
> ----- Original Message -----
> From: "Damon Chaplin" <damon ximian com>
> To: "Matthias Clasen" <matthiasc poet de>
> Cc: <gtk-doc-list gnome org>
> Sent: Thursday, October 18, 2001 12:38 AM
> Subject: Re: docbook markup in inline docs
>
>
> > On Wed, 2001-10-17 at 03:07, Matthias Clasen wrote:
> > > Damon, any progress with the sgml-mode idea for gtk-doc ?
> > > I have put a patch in bugzilla which adds an --sgml-mode option
> > > to gtkdoc-mkdb, any comments on that ? It would be really
> > > nice to get something like that included. (There are some more
> > > outstanding patches in bugzilla, but this one is the most important
> > > one for me.)
> >
> > I've applied it. Thanks for the patches. (Keep it up and you can take
> > over maintainership of gtk-doc ;)
> >
>
> No thanks. But speaking about mainership, wouldn't it be a nice idea
> to relase a 0.8 with the sgml mode stuff (of course, I should have included
> at least a tiny piece of documentation for it). Or is it ok for gtk+ and
> glib
> API docs to depend on CVS gtk-doc for proper processing ?
This has typically been the case. I have some intention (never got around
to actually doing it) of making the default --disable-gtk-doc
except when you run autogen.sh.
A new release wouldn't hurt, but I wouldn't bother waiting for
a release to depend on new gtk-doc features.
The most important place for the docs to keep working is the
autobuild on developer.gnome.org and that pulls the latest gtk-doc
every time.
> > > On to new questions:
> > >
> > > 1) gtk-doc treats "Standard" GObject functions and macros be not
> > > documenting them at all. Are there any ideas to change this, eg by
> > > refering to a section in the GObject docs describing the standard
> > > definitions ? What are the standard definitions for a GObject type,
> > > and what do we do if only some of the standard definitions are there ?
> > > (this question came up when I put a patch in bugzilla which would
> > > move all standard defines in Pango in the Standard sections, thereby
> > > effectively making them undocumented)
> >
> > I think we always intended to include a page about standard macros
> > and functions, and probably link to it from each object.
> > Maybe we should list the standard macros/funcs somewhere
> > in the object's docs, and link to the descriptions there.
> >
> > You can see the standard defs by looking at the $MODULE-section.txt
> > file, e.g. from glib 2:
> >
> > <SUBSECTION Standard>
> > G_TYPE_PLUGIN
> > G_IS_TYPE_PLUGIN
> > G_TYPE_TYPE_PLUGIN
> > g_type_plugin_get_type
Should be noted that the get_type() is really "private" not
standard - people shouldn't be using it directly in almost
any case and a few types do have non-standard TYPE macros.
> > G_TYPE_PLUGIN_CLASS
> > G_IS_TYPE_PLUGIN_CLASS
> > G_TYPE_PLUGIN_GET_CLASS
> >
> > If a type doesn't have all the standard defs, I'd guess it is a bug.
>
> The enums in Pango often only have G_TYPE_FOO.
None of the above "standard macros" apply to an enumeration type.
My original comment to Matthias was that I thought that enumeration
type macros should be with the macro, since I suspect people
will have trouble grasping the rule: "For PangoWeight,
there will be a macro PANGO_TYPE_WEIGHT"
I would imagine having immediately after the enumeration docs, something
like:
PANGO_TYPE_WEIGHT - the GObject type for PangoWeight
I don't think a lot of detail is necessary. If it is, we could
have a small description and then link to a longer documentation
section on type macros.
Regards,
Owen
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]