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/<package>. However, GIMP produces it's documentation under /usr/local/gimp/share/<gimp library directory>. Shouldn't those <gimp library directories> go under /usr/local/gimp/share/gimp? Maybe I just built things incorrectly. -- Michael J. Hammel Senior Software Engineer mjhammel@xxxxxxxxxxxxxxxxx http://graphics-muse.org ------------------------------------------------------------------------------ It's hard to believe that he beat 1,000,000 other sperm to the egg. -- From a real employee performance evaluation. _______________________________________________ Gimp-developer mailing list Gimp-developer@xxxxxxxxxxxxxxxxxxxxxx https://lists.XCF.Berkeley.EDU/mailman/listinfo/gimp-developer
