Re: gtk-doc manuals

[Aaron Weber <aaron ximian com>]

David:
  I may need quite a bit of help-- I'm not much of a programmer, so I
don't know the best ways to go about documenting APIs directly.

I've got reasonably good information on how the gtk-doc system itself
works now... not quite what I thought it was the first time:

1) You paste some special code into your makefiles.
2) At make/make install gtk-doc does its thing; you never run it
actively.
3) gtk-doc Extracts specially-designated comments from .h files and
creates SGML templates and section-listing/organizational files
4) Edit those files by hand
5) gtk-doc does its thing next time you make/make install. 

There are several things that developers need to have spelled out for
them, some of which are already available, and some of which are not: 

* What code exactly gets pasted into which Makefiles?
* What comments need to be added to .h files, and how should they be
formatted?
* What happens when you make install after editing the template files?
* Where do the finished docs show up for other developers to read them?
* How do you contribute to developer docs if you didn't write the
original software?
* What's the best way to document particular sorts of objects or
functions?


Also we need to provide the .emacs elisp function that automatically
inserts that comment structure (this is floating around; I think JPR has
a copy of it)

The way I see it there are a couple of types of people who will be
reading this information: either the actual project hackers, or more
peripheral people who want to add to developer docs but aren't actually
contributing a lot to the code itself. The first group probably doesn't
need as much hand-holding as the other, but they'll both want to have a
lot of information available, and probably some good, well-commented
examples.  

As I mentioned earlier, a lot of this is already available in one or
another place, so significant portions of the task will be organizing,
sorting, updating, and so forth: we want to make sure that it's all in
one place, and easy to maintain, so that when it changes, we don't have
an out-of-date version posted somewhere... 

Gtk+, fortunately, provides lots of great examples, so we're mostly set
there.

I do think we should have a man page, even if it just says "gtk-doc is
not run at the command line. This manual page is not used. See the file
doc/setting-up.txt or the page
developer.gnome.org/gtk-doc/instructions.php"

a.




On Sat, 2003-11-15 at 12:11, David Hackler wrote:
> if you need any help with the manual just drop me a line. I would love
> to help with this project.
> 
> David Hackler
> 
>