This is the mail archive of the guile@sourceware.cygnus.com mailing list for the Guile project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

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>&nbsp;:</entry>
<entry></entry></row>
<row><entry align="right"><emphasis>Returns</emphasis>
:</entry><entry>

</entry></row>
</tbody></tgroup></informaltable></refsect2>

Havoc


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]