Hi,

On Thu, 2007-02-08 at 01:28 +0100, Mu wrote:

I thought in putting comments in the code as I achieve to understanding functions and files, and submitting them as patche. I want to know if you think it is a good idea or it would be a useless task, or if there is some reason for leaving things as they are now.

We would appreciate if someone commented some more of the internal functions with well-written gtk-doc style comments. That would improve the documentation of the core as seen on http://developer.gimp.org/api/2.0/app/index.html

Sven

On Thu, 2007-02-08 at 08:14 +0100, Sven Neumann wrote:

We would appreciate if someone commented some more of the internal functions with well-written gtk-doc style comments. That would improve the documentation of the core as seen on http://developer.gimp.org/api/2.0/app/index.html

Since I had just been mulling around the colorize functions, I thought I'd give this a try. It's not as easy as one would hope. (Please don't take this as a complaint, but rather a description of a process that could use some streamlining.)

First, the gtk-doc project (http://www.gtk.org/gtk-doc/) has no documentation on how to use it's tagging (the gtk-doc source says there is a manual, but it points to a non-existant directory when it tells you where to look for it). Not very encouraging for a documentation tool. But I got around this by grep'ing lots of the GIMP core for examples (searched for "\* @"). There should probably be something in the HACKING or README files about where to get information on working on API documentation, specifically rules or tips on tagging and formatting (eg. how does one format a list in a gtk-doc comment section and how does one create preformatted text?). I googled for such info but only found links to source repositories for gtk-doc. Maybe no one's written such a document for use with gtk-doc.

Second, once you make the appropriate changes to the core, you try to build with --enable-gtk-doc, but that only builds the gimp API library docs. So I dug around the developer web site to find where the docs would live after being built (found it in the FAQ), and stumbled into the devel-docs directory.

Third, it turns out the core docs don't get built with --enabled-gtk-doc, but you won't know that unless you read the README in the devel-docs (which you didn't think to look for until you read the FAQ on the developer site). Unfortunately, the note in the README doesn't say how to build the core docs. As a guess, I changed into devel-docs/app and ran make, but it fails with:

../../app/core/libappcore.a(gimpimage-undo-push.o): In function `gimp_image_undo_push_vectors_reposition': /home/mjhammel/src/graphics/gimp/gimp/app/core/gimpimage-undo-push.c:800: undefined reference to `gimp_vectors_prop_undo_get_type' ../../app/core/libappcore.a(gimpimage-undo-push.o): In function `gimp_image_undo_push_vectors_mod':
/home/mjhammel/src/graphics/gimp/gimp/app/core/gimpimage-undo-push.c:777: undefined reference to `gimp_vectors_mod_undo_get_type' ../../app/core/libappcore.a(gimpimage-undo-push.o): In function `gimp_image_undo_push_vectors_remove': /home/mjhammel/src/graphics/gimp/gimp/app/core/gimpimage-undo-push.c:752: undefined reference to `gimp_vectors_undo_get_type' ../../app/core/libappcore.a(gimpimage-undo-push.o): In function `gimp_image_undo_push_vectors_add':
/home/mjhammel/src/graphics/gimp/gimp/app/core/gimpimage-undo-push.c:729: undefined reference to `gimp_vectors_undo_get_type' collect2: ld returned 1 exit status
Linking of scanner failed:

It looks like the scanner wants to be linked to something in a higher level directory but that doesn't work, at least not if built from within the app directory.

Have I missed something? Is there a top-level target that should be run to build the core API docs? I didn't see one but I might have missed it.

As an aside to this, I noticed that when I built the prerequisite software for GIMP, which I installed under /usr/local/gimp, they produced their documentation under /usr/local/gimp/share/. However, GIMP produces it's documentation under /usr/local/gimp/share/. Shouldn't those go under /usr/local/gimp/share/gimp? Maybe I just built things incorrectly.

Hi,

Until now there has been no interest whatsoever in building these docs. That's why it's something that only me and Mitch do occasionally and that's why it's undocumented and disabled by default.

If the build fails for you, your SVN checkout is outdated. I fixed the build yesterday already.

Sven