libnih
libnih copied to clipboard
keybuk
Add gtkdoc libnih API docs generation.
This add gtkdoc generated API docs for nih/*.h Also fixes up a few markup errors.
published at http://libnih.la
I don't think there's a good reason to add an external dependency on gtkdoc; after all, it comes from glib/GTK+ and if you have that lying around, why not use glib instead of libnih?
Also there are a bunch of issues with the resulting generated docs, for example the lack of structure contents.
It's a compile time option to enable generating docs, which is off by default. If gtk-doc.make is included, autoreconf would also work without the optional gtk-doc-tools dependency.
I've used gtk-doc, because existing doc comments are in gtk-doc format. There are many other projects that use gtk-doc purely for API reference, without being part of "glib/GTK+" eco-system. E.g. https://www.kernel.org/pub/linux/utils/util-linux/v2.24/libblkid-docs/ gtk-doc is not ideal, I'd rather have used doxygen, which allows to document "static" and private API as well as public one (e.g. similar to dbus API docs).
It's just API docs to help hacking on libnih or projects that depend on libnih. And since they can be generated & published, one doesn't need to have glib/GTK+ lying around, nor able to use it / target to use it.
When coding on projects that use libnih, I find it helpful to do api reference lookups, which is integrated with devhelp / emacs, instead of manually using locally generated CTAGS to jump into libnih source tree. There is now a growing amount of projects using nih, nih-dbus, nih-dbus-tool and there are requests for developer API docs. E.g. Nih demo / tutorial at http://people.canonical.com/~jhunt/presentations/uds-r/2012-10-31/upstart-development.pdf and http://upstart.ubuntu.com/cookbook/#nih
I agree there are plenty of issues with the resulting docs. But even in its current state they are a good API reference.
By your own argument, it's therefore not necessary for the libnih source tree to carry support for generating these documents since they have been published already.
There's no need to have two websites.
And without the strict definitions they're not entirely useful since libnih, by design, explicitly permits accessing struct members and doesn't provide accessors
On Friday, December 6, 2013, xnox wrote:
It's a compile time option to enable generating docs, which is off by default. If gtk-doc.make is included, autoreconf would also work without the optional gtk-doc-tools dependency.
I've used gtk-doc, because existing doc comments are in gtk-doc format. There are many other projects that use gtk-doc purely for API reference, without being part of "glib/GTK+" eco-system. E.g. https://www.kernel.org/pub/linux/utils/util-linux/v2.24/libblkid-docs/gtk-doc is not ideal, I'd rather have used doxygen, which allows to document "static" and private API as well as public one (e.g. similar to dbus API docs).
It's just API docs to help hacking on libnih or projects that depend on libnih. And since they can be generated & published, one doesn't need to have glib/GTK+ lying around, nor able to use it / target to use it.
When coding on projects that use libnih, I find it helpful to do api reference lookups, which is integrated with devhelp / emacs, instead of manually using locally generated CTAGS to jump into libnih source tree. There is now a growing amount of projects using nih, nih-dbus, nih-dbus-tool and there are requests for developer API docs. E.g. Nih demo / tutorial at http://people.canonical.com/~jhunt/presentations/uds-r/2012-10-31/upstart-development.pdfand http://upstart.ubuntu.com/cookbook/#nih
I agree there are plenty of issues with the resulting docs. But even in its current state they are a good API reference.
— Reply to this email directly or view it on GitHubhttps://github.com/keybuk/libnih/pull/10#issuecomment-30042998 .
Have you ever, ever felt like this? Had strange things happen? Are you going round the twist?
It's not necessary to carry them, but it is a good practice to carry them together with the source.
websites come and go, the source codes seem to survive so it's the best place to keep it all together.
They are useful to the extend of their usefulness =) docs can be continuously improved, it's not like documentation affects api/abi.