I wondered how to document virtual methods in a class and looked around
gio, since this is a prime example of
In doing so, I noticed the following:
1.) Virtual methods in a class structure seem to be rarely used. Instead, types like
GAction use custom type interfaces. Is there a general shift towards type interfaces rather than virtual methods in a class? Obviously, documenting a type interface like
GFileIface is straight-forward and also correctly showing up in the general documentation, so I guess that this is the preferred method of implementing and using virtual functions nowadays?
2.) Some classes are still using virtual methods, but only a few seem to actually document functions (and even if they do, most of the time only some of them). I’ve found
GResolver as an example of that. The caveat there is that the virtual methods are documented using the
Class::function syntax, which, according to the gtk-doc manual on documentation syntax, is the syntax for a signal. That’s misleading in this case, since the documentation is for a different concept - virtual methods - and not signals. (Yes, implementation-wise, both signals and virtual methods are the same, but not conceptually.)
3.) Even for those documented virtual methods, the documentation doesn’t show up anywhere on the web. For instance, I tried to find the resulting documentation for this paragraph:
* This is identical to GResolverClass::lookup_by_name except it takes * @flags which modifies the behavior of the lookup. See #GResolverNameLookupFlags * for more details.
via a simple web search for
"except it takes flags which modifies the behavior of the lookup." (quotes are literal and part of the search query, of course, because we’re interested in text exactly appearing like this), but it turned up no relevant results. It’s definitely not part of the
GResolver documentation, but I was curious to find out if there was more specific documentation for
GResolverClass, which doesn’t seem to be the case.
So, currently, it looks like there’s no proper way to document virtual class methods. Is that a bug in
gtk-doc does seem to parse documentation for signals alright and publish it, but stops after finding a comment like
/* Virtual methods */.
Using a type interface, the contained methods can be documented (a bit) with a top-level comment and the documentation is published in a sane manner by gtk-doc. Is this the way to go for new code rather than embedding virtual functions in the class structure?
Even then, there is a problem with documenting type interfaces. You can’t really document functions properly that way. Giving a short description is possible, but it’s impossible to document parameters, return types or even write up a nice long description.
So, really, no solution is really satisfactory. Documenting the functions inline (like in the virtual-methods-class example) is really the best solution, but it’s a bit useless if the documentation is not being generated/published anywhere. Mixing inline documentation with a type interface would sound interesting, but… the inline documentation probably won’t show up either.