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
undefined reference to `gimp_vectors_prop_undo_get_type'
../../app/core/libappcore.a(gimpimage-undo-push.o): In function
undefined reference to `gimp_vectors_mod_undo_get_type'
../../app/core/libappcore.a(gimpimage-undo-push.o): In function
undefined reference to `gimp_vectors_undo_get_type'
../../app/core/libappcore.a(gimpimage-undo-push.o): In function
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

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
[EMAIL PROTECTED]                           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

Reply via email to