Re: EuGTK 4.7.5 available
- Posted by jimcbrown (admin) Dec 31, 2013
- 1647 views
Having documentation embedded in the source code is ok (even if it gets in the way sometimes).
As far as I can tell, the docs included with EuGTK include almost NO function documentation at all.
This is for two reasons: first of all, the docs supplied by gtk.org take care of that, no need for me to repeat their work. Second of all, mine weren't intended to explain how the different functions work, they were designed to illustrate how to use EuGTK.
I think this makes a lot of sense. Of course, this is kind of a special case (a language-specific wrapper for an already documented library). (Ok, a very common special case.) However, this rationale wouldn't apply to the doc writers for Euphoria's standard library, for example.
But two questions remain: How do you include images in the docs? You can hardly expect to document a GUI without showing some pix.
Agreed. Although, including images as part of function documentation is kind of unusual.
And where is the appropriate place to put the documentation on the full package, not just those for a particular function?
IOW, embedding doc strings in source code is fine as far as it goes, but doesn't begin to provide a full solution.
Agreed. For the standard library, we have special text files, such as the entirely hand-generated release notes and the entirely hand-generated introduction/beginners docs (some of which are derived from the original refman doc). eudoc is told, in addition to looking at the include files that make up the standard library, to look at these text files as well, and to generate the documentation from them.
I think that the markup language that eudoc uses has some support for images, as it's also told where to look for the original graphics files so it can embed them in the HTML version.
