Comments on: 23.02.2006 The Beast Documentation Quest (2)

By: Zack Weinberg

Zack Weinberg — Wed, 30 Nov -0001 00:00:00 +0000

I can’t tell from your tone if you’ve yet found what you need, but if you haven’t, Synopsis might be it, at least as far as extracting documentation from C++ sources.

By: sebn

sebn — Wed, 30 Nov -0001 00:00:00 +0000

I also use Synopsis.
But I didn’t found any tool that really match my needs. And I think that starting another documentation project would be totally useless. Instead, we should probably design some source code description (AST, like in Synopsis ?) standard XML schema, and some library (and other languages bindings) to handle matching documents. Then, people could start various parser/formatter projects that would match their needs and work together.

By: Stefan Kost

Stefan Kost — Wed, 30 Nov -0001 00:00:00 +0000

Well one of the bigger problems is that there isn’t a C or C++ parser out there, as what we write down into .c or .cpp files isn’t C or C++. – it is C or C++ *before beeing processed by the preprocessor. This bring lots of challenges for a parser :(

Anyway some people (including me), trying to improve gtk-doc as far as possible to generate better docs. IHMO using the same doc-utile and thus allowing x-refs inbetween is crucial for a paltform (GNOME).

By: Eero Tamminen

Eero Tamminen — Wed, 30 Nov -0001 00:00:00 +0000

Python has a lot of support modules for parsing both different programming languages[1] and structured text formats (be it XML or something else), so maybe something could be done by cobbling together some already existing Python stuff and writing the rest from scratch?

[1] I’m not sure about C++ though.

By: Eero Tamminen

Eero Tamminen — Wed, 30 Nov -0001 00:00:00 +0000

Ahem, I just noticed that the Synopsis tool mentioned above can both be used from Python and parse C++:
http://synopsis.fresco.org/Manual/html/ch03s01.html