Got Gtk-Doc working. Now all the fancy /** comments before the functions
authorfliep <fliep@ddfedd41-794f-dd11-ae45-00112f111e67>
Sun, 29 Mar 2009 01:13:07 +0000 (01:13 +0000)
committerfliep <fliep@ddfedd41-794f-dd11-ae45-00112f111e67>
Sun, 29 Mar 2009 01:13:07 +0000 (01:13 +0000)
commit904fed6618b22e84597efd60c3784e57d44f3ef1
treee6bb1597887d3d5d8428ca14624158dd1d2ada68
parent16a17e66c632c5f0a654a3999b57eeb61730a473
Got Gtk-Doc working. Now all the fancy /** comments before the functions
actually mean something. To use gtk-doc, invoke configure like this:

./configure --enable-gtk-doc

When you do this, configure will generate makefiles that rebuild the docs
whenever the source is changed. Calling configure without that option
generates makefiles that don't rebuild the docs. Building the docs takes
some time so you probably want to disable it unless you're actively working
on the docs.

The documentation is output as HTML, which you can browse by pointing your
browser to

file:///path/to/chimara/docs/reference/html/index.html

The really cool thing is that the docs are also built as a devhelp module,
so when you make install, the devhelp module is installed and automatically
shows up in Devhelp.

The documentation consists of two sections: one is the API of our widget,
the other is the Glk API specification which we have been working from. I
have obtained permission from Andrew Plotkin to include and alter this spec.
I have changed the order of things around a little bit so it makes more
sense as a Gtk-Doc reference book.

The API spec only contains the parts that we have implemented so far. I
figure if we update the documentation for the Glk API functions as we
implement them, then we'll be able to see at a glance how far we've gotten.

One more change left to describe: the new file src/doc.c consists of only
comments. These comments contain two things. One is the introductory
descriptions of each Gtk-Doc section. I put these in here because they
really bloated the regular C files. The other is the Gtk-Doc comments for
constants and structures that are defined in glk.h. I put these in here
because the spec says glk.h is supposed to be the same on every platform
except for the typedefs of the 32-bit types.
42 files changed:
Makefile.am
autogen.sh
configure.ac
docs/.svnignore [new file with mode: 0644]
docs/Makefile.am [new file with mode: 0644]
docs/reference/.svnignore [new file with mode: 0644]
docs/reference/Makefile.am [new file with mode: 0644]
docs/reference/chimara-docs.sgml [new file with mode: 0644]
docs/reference/chimara-sections.txt [new file with mode: 0644]
docs/reference/chimara.types [new file with mode: 0644]
docs/reference/glk-api-conventions.sgml [new file with mode: 0644]
docs/reference/glk-character-encoding.sgml [new file with mode: 0644]
docs/reference/glk-display-style.sgml [new file with mode: 0644]
docs/reference/glk-front-matter.sgml [new file with mode: 0644]
docs/reference/glk-introduction.sgml [new file with mode: 0644]
docs/reference/glk-line-input.sgml [new file with mode: 0644]
docs/reference/glk-main-function.sgml [new file with mode: 0644]
docs/reference/glk-other-events.sgml [new file with mode: 0644]
docs/reference/glk-output.sgml [new file with mode: 0644]
docs/reference/glk-window-arrangement.sgml [new file with mode: 0644]
docs/reference/glk-windows.sgml [new file with mode: 0644]
docs/reference/version.xml.in [new file with mode: 0644]
po/.ignore [deleted file]
src/Makefile.am
src/abort.c
src/case.c
src/chimara-glk-private.h
src/chimara-glk.c
src/chimara-glk.h
src/doc.c [new file with mode: 0644]
src/event.c
src/fileref.c
src/fileref.h
src/gestalt.c
src/glk.c
src/input.c
src/stream.c
src/stream.h
src/strio.c
src/style.c
src/window.c
src/window.h