GNOME Bugzilla – Bug 92861
improve searchability of generated docs
Last modified: 2004-12-22 21:47:04 UTC
Hi, I'm a newbie with GTK. As such, I always have trouble finding the right function for something. Most of the time, I know parts of the name, but not enough to get the function name correct. Usually, I throw my keywords against Google and see what comes up. This approach, however, doesn't really work with the API web docs, as they list the correct name and that's it. Now, here is my suggestion: For each function, macro, constant, type etc., mention it again with the underscores replaced by a space. For example, gtk_viewport_set_shadow_type would also be listed as "gtk viewport set shadow type". This allows search engines to match the single words, and I am sure this would rank the right API webpage for a function much higher than it is now. The question is where to add these "alternative names"... HTML comments, meta tags, a dedicated keyword section (in a smaller font perhaps) could be feasible. I don't know how the web pages are generated, so I don't make a comment on how feasible this is. Cheers, Colin
I think this is a gtk-doc bug, because we would need gtk-doc changes to implement this or some other solution, e.g. an index of functions (which I would favour).
Here is a patch to make gtk-doc support index creation. In order to use it, simply add an <index/> element at the proper spot in your driver document. gtk-doc emits two index entries per symbol, one primary one and a secondary one under the symbol type, e.g. the G_LIKELY() macro will produce an entry "G_LIKELY()" under "G" and an entry "macros, G_LIKELY()" under "M".
Created attachment 16647 [details] [review] patch
I was going to file this same feature request (for an index), and came upon this bug. I think it's a very important feature of api docs that gtk-doc has been sorely missing! Matthias's patch works quite well. You can look at the results here: http://www.columbia.edu/~nlevitt/tmp/glib/ix01.html There seems to be a bug in the #id????????? anchors generation. Also, since the index page can get quite huge, I would suggest removing the "functions" entry, and probably the others (macros, enums) as well. It's a good idea, but I think the entries would work better as separate pages (an index of functions, index of macros, etc.). That can be a future enhancement though. Am attaching a version of the patch without the "functions" etc. entries; you can see results here: http://www.columbia.edu/~nlevitt/tmp/glib2/ix01.html
Created attachment 16828 [details] [review] less functional patch :)
I originally planned to have separate indices for functions, enums, etc, but it seems that DocBook doesn't support more than one index.
I've committed the less functional patch now.