Re: Documenting the source?
Hi, I have some experience documenting the C/C++ source of a project. For the DODS project (http://unidata.ucar.edu/packages/dods) I use a package called doc++ which is barely supported, but works well. Doc++ has a home page, and we support a slightly modified (i.e. debugged) version of it. It creates html and LaTeX, and works well with hyperlatex and a set of LaTeX macros I've developed for the same project. It's not as sexy and au courant as XML and DTDs, but it is simple and works, and creates hard copy and web output equally well. You can find more at http://top.gso.uri.edu/dods.html . The documentation on that page was made with this package, and the programmer's ref was generated with the doc++ stuff. Well, does it support the GTK+ object system like gtk-doc does? I guess not and that's why I suggest that we stop discussing what tool to use since I doubt we will find something better suited to our needs. To explain what I mean, here are a few lines out of the README explaining the important part: gtkdoc-scanobj: Creates a small C program which is compiled and run to query your library about which GtkObjects it contains, the signals they emit, and any Args they have. If your module has no GtkObjects then you don't need to use this. Our module contains GtkObjects, so we might come to the conclusion that we absolutely need to use this. Salut, Sven
Re: Documenting the source?
[EMAIL PROTECTED] (Sven Neumann) writes: Hi, I have some experience documenting the C/C++ source of a project. For the DODS project (http://unidata.ucar.edu/packages/dods) I use a package called doc++ which is barely supported, but works well. Doc++ has a home page, and we support a slightly modified (i.e. debugged) version of it. It creates html and LaTeX, and works well with hyperlatex and a set of LaTeX macros I've developed for the same project. It's not as sexy and au courant as XML and DTDs, but it is simple and works, and creates hard copy and web output equally well. You can find more at http://top.gso.uri.edu/dods.html . The documentation on that page was made with this package, and the programmer's ref was generated with the doc++ stuff. Well, does it support the GTK+ object system like gtk-doc does? I guess not and that's why I suggest that we stop discussing what tool to use since I doubt we will find something better suited to our needs. To explain what I mean, here are a few lines out of the README explaining the important part: gtkdoc-scanobj: Creates a small C program which is compiled and run to query your library about which GtkObjects it contains, the signals they emit, and any Args they have. If your module has no GtkObjects then you don't need to use this. Our module contains GtkObjects, so we might come to the conclusion that we absolutely need to use this. I second this. doc++ is nice, but we really want to use gtk-doc.
Re: Documenting the source?
On 2 Feb, Sven Neumann wrote: /** * gimp_size_entry_new: * @number_of_fields: the number of entries * @unit: the default unit * @unit_format: a pointer to a format string describing the unit The good thing is that gtk-doc checks that the documentation and the source are in sync and it creates DocBook SGML that can be used to create nicely linked HTML. In the example above all gimp-specific types and enums (GUnit, GimpSizeEntryUP, GimpSizeEntry) would be linked to their declaration. But I guess you have worked with the glib and gtk+ reference manuals before and know how the output looks like. Hm, yes, but the gtk+ manual is not quite what I had in mind. I thought of really in-source-documentation and looking at your example code I think you had the same in mind. But I would like to use a standard not a new solution, therefor your examplecode doesn't match my thoughts. Defining the documentation of the parameters directly by giving every one unified metatag is very restricting. Javadoc like sourcecode has a better approach: @memo short documentation @doc long documentation @returndoc of return value of a function @param doc of parameter of a function @exception doc for exepction thrown by a function @see cross reference @authorauthor @version version There are at least a few dozen programms which can extract this and export them to at least that number of formats. Have a look at doc++, a very cute program to generate documentation... -- Servus, Daniel
Re: Documenting the source?
On 2 Feb, Sven Neumann wrote: Well, does it support the GTK+ object system like gtk-doc does? I guess not and that's why I suggest that we stop discussing what tool to use since I doubt we will find something better suited to our needs. It supports crossreferences, what else do you want? -- Servus, Daniel
Documenting the source?
Hi developers, Having no real documentation of the sourcecode is really a burden when searching for bugs. Do you agree that having a documentation would be fine? I'd like to introduce a in-source-documentation which an extractor program could use to make a TeX or HTML file of it. Using javadoc like comments we'd always have a specification of a function handy without having to guess the sense. -- Servus, Daniel
Re: Documenting the source?
On 2 Feb, Sven Neumann wrote: We have already brought up this issue lately and I think the conclusion was that we try to add documentation for libgimp before 1.2. Most certainly we will use gtk-doc with comments embedded into the source. Marc volunteered to write the necessary scripts to convert the info out of the PDB. What characters does gtk-doc use to introduce a comment? I like the idea of having javadoc like comments i.e. /** */ with some special tags because there are several programms out their which make beatyful documentation out of this and it's quite a standard solution... I volunteer to do some of this documentation... I have to get the sense anyway... :)) -- Servus, Daniel
