Contents
The gtkdoc tool started as some little perl script to generate API documentation in DocBook xml format and control the conversion to html and the like. Even though that works nicely there is space for improvements. Ideas can be also gathered by having a closer look at similar tools such as Doxygen and Javadoc.
Please freely add your ideas and comments below. There are more ideas in gtk-docs TODO in git repository.
get rid of .types files
Can't we have another section-delimitter in the -section.txt file and use all symbols in there. The includes can be read from the section too. Example
<SECTION> ... <SUBSECTION Types> gtk_widget_get_type </SECTION
TommiKomulainen: gtk-doc is already parsing headers for function signatures. Why can't it just collect the *_get_type() functions and use them automatically?
StefanKost: gtkdoc-scan >=1.8 can be told via SCAN_OPTIONS to --rebuild-types (also --rebuild-sections if wanted)
provide access to the sgml document
For IDEs it would be cool to have an API to get the doc-block by symbol-names. This basically involves installing the DocBook xml too and adding the docbook id to a devhelp alike index file. The functionality would ideally be provided by a little c library.
On the other hand the question is, who apart from an IDE would use this? If nobody does, we can just standardise the index file and leave the implementation to the IDE developers.
RossBurton: If you add <index></index> to the sgml file then the generated HTML will have an index, based on index.sgml in the html/ directory. With a little tweaking this could be installed along with docbook files, and the devhelp file not needed. StefanKost: I usually do this. But IMHO this isn't what we need to get the proposed feature. An IDE does not want an HTML fragment. I very likely wants to have something that can be easily shown in a tooltip, like plain text.
links to man-pages
MatthiasClasen: It would be very nice if devhelp could convert occurrences of standard functions like printf() into links to the man pages.
StefanKost: How could we link them? Does Gnome has a URI scheme for Yelp? Another way would be to have a tool that makes a big gtkdoc manual from the S2 man-page section and then gtkdoc-fixrefs would take care of that 
MatthiasClasen: At some point, yelp was able to display man pages, and had a URI scheme for it. I don't know if that got lost meanwhile...
StefanKost: Found it: 'yelp man:/usr/share/man/man1/cp.1.gz' Unfortunately in gnome-2.10 it says that man pages are not supported right now. Browsers like epiphany react on such uris and launch yelp. Summa-summarum, if yelp gets fixed it will work (maybe it already work in 2.12 - can anyone please check)
ChristianMeyer: Works for me in GNOME 2.12, looks like it is fixed. Could anyone else please verify?!
MaciejPiechotka: Not working in 2.24. BTW - I don't think hardcoded paths are good. I need to know the open(2) part and give it to yelp as it (man:/2/open possibly) which would finally display correct page.
JavierJardon: Works for me in GNOME 2.26, looks like it is finally fixed
ShaunMcCance: It's a compile-time option that a number of distros seem to like to turn on. It'll be turned on by default when it's ready. That could be 2.12 or it could be later. It's pretty much at the bottom of my list of priorities.
links to inherited symbols
Other docs systems like e.g. Javadoc list inherited symbols (member, methods) briefly. For gtk-doc it would be good to do this too. The brief-sections could have a link to the brief section of the parent class (or links to all parent classes). The detailed section could even list all inherited symbols as links.
modularize gtkdoc tools
The code of the tools should be moved to perl modules, so that it can be overridden by custom routines for those project which have special needs.
Currently information comes from sgml-.fragment files in the 'tmpl' dir or directly from the sources. Ideally this is configurable, where own information providers can be registered together with a rank. The rank determines the order the providers are queried. The querying continues until a provider returned docs.
ease debugging of gtkdoc tools
There are lots of commented out print statements inside the source. What about having a debug_print sub-routine, that depending on the the environment variable GTKDOC_DEBUG_LEVEL prints diagnostics or not.
Does anyone knows a way in perl to make the operation a nop easily (if env-var is not set)?
enhance gtk-doc html pages
page title
Currently the title of the html page only shows the classname. Wouldn't it be better to make this a combination of page and document name.
page header
The opposite question for the page header (navigation block). This always shows the document title. I'd rather have something like 'page-name : doc-name' here too.
allow the documentation of virtual methods
Right now one can do a typedef for the v-method function pointer and document that, or document the class struct and add the docs there.
introspect enums
Avoid the need to retype the information from enums into the docs. Check gtkdoc-scangobj.
document audience
Many gnome libraries have several audience; gtk had application and widget developers, gstreamer has application and plugin developers. It would be good to be able to markup the audience of modules and symbols. This would allow e.g. devhelp to filter the docs by purpose. The purpose-tag should be optional and only restrict the purpose from all to specific.
For the section it could be like:
SECTION:xyz @title: ... @audience: widget-developers description
For symbols it could look like:
symbol-name: @par1: ... description returns: since: xyz audience: application-developer
document run-time behaviour
In this blog the author talks about adding some performance signature to comments. We could have a 'complexity:' tag for the method docs:
symbol-name: @par1: ... description returns: complexity: low, comment
The first item after the 'complexity:' keyword should be one of {low|medium|high}. It can optionaly be followed by a comment.
getters and setters
It would be nice if gtk-doc knew about the relation between properties, their getters and setters, and could generate some nice links between them. That may require some new tags, such as Setter-for: / Sets: or Getter-for: / Gets:
StefanKost: if GtkWidget has property name, check if there is gtk_widget_get_name and/or gtk_widget_set_name and link. Should be relative easy technically. Any idea how the links should looks like? Like in a "See also:" section. Besides I wonder if we really want to promote setters and getters (makes the API big).
MaciejPiechotla: They may make api big but I guess they make it fast as well. With properties you have transformation from/into GValue and lookup by string key. Both are much slower then simple CALL.
StefanKost: check Bug536939 regarding the set/get slowness.
live editing
One problem with documentation is maintenance. Wiki like projects seem to suffer a bit less from this as it is easy to update thinks. gtk-doc in trunk can add links to the right of a doc-blob (ifdef'ed out right now). There are two examples - an link to do a google code search and a edit link. The idea of the edit link is that it calls a configurable cgi and passes doc-module + symbol. Thats the easy part. What is missing.
- latest docs: we need a set of api-doc built from latests sources - it does not make sense to change released sources. this could work as a build-slave in the build-brigade. The builder should run an up-to-date version of gtk-doc (could be updated as needed)
the cgi would need to need to have a hashmap of docmodule:symbol -> file:line_start:line_end to efficiently fetch the docblob for editing. the cgi should run on the same machine as the builder to have access to the latest sources
- the hashmap could be build by scanning all Makefile.am in the sources for "DOC_MODULE=xyz" and "DOC_SOURCE_DIR=xyz" lines
- the cgi should allow the editor to put his user-name and email-address and store it in a cookie for patch attribution
- we need to decide what to do with the patch:
# send to bugzilla (e.g. like done in bug-buddy, look for bugzilla_create_report), this would require that we can also map from docmodule to bugtracker:product:component
- Do NOT use the Bug-Buddy method to create bugs in Bugzilla. It is a local hack meant for Bug-Buddy usage only.
- Any pointers how to do it properly then?
- in any case the shown latest docs would include the editits, dunno if we want to somehow show that this is a pending modification
JavierJardon: Vala documentation project has live editing capabilities: http://valadoc.org/
JavierJardon: Related bug: bug #580246: Add edit option to devhelp like monodoc
JavierJardon: related wiki page: LiveDocumentationEditing
This page belongs to the GNOME Documentation Project series, it concerns writing documentation for GNOME. Perhaps you can help out, or would like to consult the GNOME documentation.
