This is the mail archive of the
guile@sourceware.cygnus.com
mailing list for the Guile project.
Re: Doc Tasks (was RE: docstrings in Guile!)
Maciej Stachowiak <mstachow@alum.mit.edu> writes:
> Guile basically _is_ more or less doing something similar insofar as being
> in sync with the source is concerned. I am not sure about teh value of
> the value of the manual editing step. Wouldn't that allow the manual
> to fall quite out of sync with the source, if actually used?
>
It's fairly neat how it works. You don't have to put comments in
the code if you don't want; then gtk-doc just generates blank
templates like this:
<!-- ##### FUNCTION gconf_file_exists ##### -->
<para>
</para>
@filename:
@Returns:
You fill that in; as long as you don't touch the magic comments
gtk-doc can merge changes to function parameters in, much like CVS
conflict resolution.
For gconf I don't use the inline comments, just out of personal
preference. Anyway, if you do use the inline comments, you want to
avoid manual tweaking of the function descriptions but you can still
fill in other parts of the template file such as an introduction at
the beginning, etc. and gtk-doc handles merging of your stuff with the
stuff in the code.
gtk-doc can then generate full DocBook from the template, for example
that above becomes:
<refsect2>
<title><anchor id="gconf-file-exists">gconf_file_exists ()</title>
<programlisting><link linkend="gboolean">gboolean</link>
gconf_file_exists
(const <link linkend="gchar">gchar</link>
*filename);</programlistin
g>
<para>
</para><informaltable pgwide=1 frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry
align="right"><parameter>filename</parameter> :</entry>
<entry></entry></row>
<row><entry align="right"><emphasis>Returns</emphasis>
:</entry><entry>
</entry></row>
</tbody></tgroup></informaltable></refsect2>
Havoc