GNOME Bugzilla – Bug 142647
all docs included in the source code
Last modified: 2005-02-05 12:40:04 UTC
From the mailinglist: On Thu, May 13, 2004 at 12:17:24PM +0100, Damon Chaplin wrote: > On Thu, 2004-05-13 at 10:13, Stefan Kost wrote: > > ... and another answer, > > > > it sometimes helps to do 'rm docs/reference/*.stamp'. > > The defines, structs and so on can be documented in the source ;-) > > Remains the question, if these sections can be documented in the source? > > ##### SECTION Title ##### > > ##### SECTION Short_Description ##### > > ##### SECTION Long_Description ##### > > ##### SECTION See_Also ##### > > And if so how? When looking at gtkdoc-scan it look like it extracts > > comments for MACROS, TYPEDEF'D FUNCTIONS, ENUMS, STRUCTS, UNIONS, > > VARIABLES (extern'ed variables), FUNCTIONS. > > Is it gtkdoc-mktmpl that actually extracts data from source comments? > > ReadSourceDocumentation() in gtkdoc-mkdb is where the source code is > scanned for documentation. > > It would be nice if all docs could be included in the source code if > desired. > > Damon
You can almost do this. gtk-docs puts all this stuff in its big hashtable under keys like $TMPL_DIR/$filename:Long_Description which end up like ./tmpl/gdkscreen:Long_Description: Now you can put comments like /** * ./tmpl/gdkscreen:Long_Description: * * TEST TEST TEST */ into your source files and hope that gtk-doc picks this up. The only reason why it doesn't currently is that it doesn't accept . and / in symbol names (see ScanSourceFile in gtkdoc-mkdb). The other problem with this approach is that you don't really want to expose the values of $TMPL_DIR and $filename in your source files, maybe by using symbols of the form GdkScreen:::Long_Description and then have gtk-doc figure out the filename which this belongs to by looking for the object in the sections file...
*** This bug has been marked as a duplicate of 165963 ***