Re: Feature request: generate documentation from C files

[Simon Josefsson]

Alper Ersoy <address@hidden> writes:

> Hello Simon,
>
> Simon Josefsson:
>> I'm using doxygen, but I think I wasn't clear on the feature I think
>> is the most important in the tool I want: generating a texinfo block
>> for _one function only_.  Doxygen (and GTK-DOC-tools for that matter)
>> appear to output entire sets of HTML files documenting the entire
>> package, and this is not useful if you want to write a texinfo manual
>> that look like:
>
> I have both good and bad news for you.
>
> Good news is, we already create texinfo docs from GTK-DOC style
> C comments in BEAST/BSE project.
>
> Bad news is, it's usually a monolithic file :\
>
> You can see a few examples here:
>
>   http://beast.gtk.org/documentation.html
>
> See below ``API Reference'' on the left side.  You are interested in
> ``BSE Structs'' and ``SFI Functions.''  You can also take a look at
> the files under ``Development.''

Hello.  Thanks for the pointers, interesting!

One question: do you have any markup language to use within the
GTK-DOC comments, to create, e.g., lists, links, indentation?  Can you
use texinfo commands?

I will work on this next week, and unless I find some ideas on adding
markup language to GTK-DOC comments, I might switch to using doxygen
comments.  The doxygen markup language seem pretty mature.  I still
prefer the GTK-DOC tool HTML output over the (IMHO) cluttered doxygen
output, though, so I might spend time on writing a doxygen2gtkdoc.
Perhaps I will borrow the doxygen markup instead, and use it in my
GTK-DOC style comments, and do some filtering.

As for generating texinfo manual, adding a texinfo output backend to
doxygen seem to be one option.  Using your already existing texinfo
generator, and split the output to one file per function is another
option (probably easier approach).  My initial idea on extending or
rewriting my existing tool doesn't look like a good idea now.

I wonder if there is any discussion between the doxygen and
GTK-DOC-tools teams?  The doxygen comment style and markup appear to
be more advanced, but I like the GTK-DOC tools better than doxygen,
especially if you are adding texinfo support and XML support for use
within GTK applications.  The graph and diagram feature in doxygen is
also interesting, but it appear to require non-free programs so I
wouldn't use it.

Thanks,
Simon