www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Synopsis: A possible alternative to Doxygen

reply Andy Friesen <andy ikagames.com> writes:
<http://synopsis.fresco.org>

Synopsis differs from Doxygen mainly in that it is built to support 
multiple parsers and formatters.  Parsers build ASTs, formatters consume 
them.

Most of it is implemented in Python, but there is a C++ API as well.

Since we already have a complete D parser that's implemented in C++, 
connecting the two would probably be pretty straightforward. (one could 
also use SWIG to generate Python bindings, and create a parser plugin 
that way...)

  -- andy
Aug 02 2004
next sibling parent reply teqDruid <me teqdruid.com> writes:
I think my inexperience with C's got the best of me on this one.
I've got a function:
public void parse(char[] format, ...);
I want to take the variable arguments and feed them to an extern(C)
function.  I've tried:
xmlrpc_parse_value(&xmlrpcClient.env, realValue, toStringz(format),_argptr);
But although it doesn't output an error, it also doesn't appear to work. 
This does however:
xmlrpc_parse_value(&xmlrpcClient.env, realValue,
toStringz(format),va_arg!(char**)(_argptr));
If I've only got one char** argument.

How do I do what I'm trying to do?
TIA
John

On Mon, 02 Aug 2004 17:06:55 -0700, Andy Friesen wrote:

 <http://synopsis.fresco.org>
 
 Synopsis differs from Doxygen mainly in that it is built to support 
 multiple parsers and formatters.  Parsers build ASTs, formatters consume 
 them.
 
 Most of it is implemented in Python, but there is a C++ API as well.
 
 Since we already have a complete D parser that's implemented in C++, 
 connecting the two would probably be pretty straightforward. (one could 
 also use SWIG to generate Python bindings, and create a parser plugin 
 that way...)
 
   -- andy

Aug 02 2004
parent teqDruid <me teqdruid.com> writes:
Sorry. Hit the wrong button.

On Mon, 02 Aug 2004 21:56:10 -0400, teqDruid wrote:

 I think my inexperience with C's got the best of me on this one.
 I've got a function:
 public void parse(char[] format, ...);
 I want to take the variable arguments and feed them to an extern(C)
 function.  I've tried:
 xmlrpc_parse_value(&xmlrpcClient.env, realValue, toStringz(format),_argptr);
 But although it doesn't output an error, it also doesn't appear to work. 
 This does however:
 xmlrpc_parse_value(&xmlrpcClient.env, realValue,
toStringz(format),va_arg!(char**)(_argptr));
 If I've only got one char** argument.
 
 How do I do what I'm trying to do?
 TIA
 John
 
 On Mon, 02 Aug 2004 17:06:55 -0700, Andy Friesen wrote:
 
 <http://synopsis.fresco.org>
 
 Synopsis differs from Doxygen mainly in that it is built to support 
 multiple parsers and formatters.  Parsers build ASTs, formatters consume 
 them.
 
 Most of it is implemented in Python, but there is a C++ API as well.
 
 Since we already have a complete D parser that's implemented in C++, 
 connecting the two would probably be pretty straightforward. (one could 
 also use SWIG to generate Python bindings, and create a parser plugin 
 that way...)
 
   -- andy


Aug 02 2004
prev sibling parent reply Ilya Minkov <minkov cs.tum.edu> writes:
Andy Friesen schrieb:

 <http://synopsis.fresco.org>
 
 Synopsis differs from Doxygen mainly in that it is built to support 
 multiple parsers and formatters.  Parsers build ASTs, formatters consume 
 them.

I'm not that familiar with doxygen, but... doesn't it as well? Besides, i would think that simple transformation to make source C++-like would even be quite easy.
 Most of it is implemented in Python, but there is a C++ API as well.

Yikes... Couldn't it be a Python-only thing? ;) I love python, and i like C++, but i hate to have to compile extensions to use Python code.
 Since we already have a complete D parser that's implemented in C++, 
 connecting the two would probably be pretty straightforward. (one could 
 also use SWIG to generate Python bindings, and create a parser plugin 
 that way...)

No, i guess it wouldn't, because a documentation system needs comments - something a compiler's parser couldn't care less about - they are sorted out in the lexer. -eye
Aug 04 2004
parent reply Andy Friesen <andy ikagames.com> writes:
Ilya Minkov wrote:

 Andy Friesen schrieb:
 
 <http://synopsis.fresco.org>

 Synopsis differs from Doxygen mainly in that it is built to support 
 multiple parsers and formatters.  Parsers build ASTs, formatters 
 consume them.

I'm not that familiar with doxygen, but... doesn't it as well?

Doxygen isn't quite as flexible, as I understand it. If memory serves, there is only one parser, which uses a bunch of boolean flags to test various pieces of syntax, depending on the language. (feel free to correct me on this: it's been quite awhile since I looked at the doxygen source) Synopsis actually uses multiple distinct parser implementations. It currently has a Python parser as well as the OpenC++ parser. (and CPP, of course)
 Besides, i would think that simple transformation to make source 
 C++-like would even be quite easy.

It is. That's what dfilter is. :) It's somewhat hackish, though: the doxygen listings make a mess of things for which C++ has no analog. (like templates that contain multiple definitions)
 Most of it is implemented in Python, but there is a C++ API as well.

Yikes... Couldn't it be a Python-only thing? ;) I love python, and i like C++, but i hate to have to compile extensions to use Python code.

I blame C. ;) (I blame quite a lot of things on C) Luckily for the rest of humanity, Synopsis has its own PyObject wrapper that overloads a whole bunch of operators and automatically refcounts. It's pretty sane, as C++ goes. Also, it would be quite possible to write a D parser entirely in Python.
 Since we already have a complete D parser that's implemented in C++, 
 connecting the two would probably be pretty straightforward. (one 
 could also use SWIG to generate Python bindings, and create a parser 
 plugin that way...)

No, i guess it wouldn't, because a documentation system needs comments - something a compiler's parser couldn't care less about - they are sorted out in the lexer.

Right. A bit of tweakery would be certainly necessary. -- andy
Aug 04 2004
parent reply "Martin M. Pedersen" <martin moeller-pedersen.dk> writes:
"Andy Friesen" <andy ikagames.com> skrev i en meddelelse
news:cer7l8$a0i$1 digitaldaemon.com...
 Doxygen isn't quite as flexible, as I understand it.  If memory serves,
 there is only one parser, which uses a bunch of boolean flags to test
 various pieces of syntax, depending on the language. (feel free to
 correct me on this: it's been quite awhile since I looked at the doxygen
 source)

I'm not sure Synopsis is a more flexible than Doxygen. Sure, you can have other parsers. But as far as I can see from the diagrams, the nodes in the syntax tree is limited to constructs found in C++. This might be a problem. With Doxygen it is possible to document anything - its own user manual is written with Doxygen, and that isn't anything like C++. Regards, Martin
Aug 04 2004
parent reply Andy Friesen <andy ikagames.com> writes:
Martin M. Pedersen wrote:
 "Andy Friesen" <andy ikagames.com> skrev i en meddelelse
 news:cer7l8$a0i$1 digitaldaemon.com...
 
Doxygen isn't quite as flexible, as I understand it.  If memory serves,
there is only one parser, which uses a bunch of boolean flags to test
various pieces of syntax, depending on the language. (feel free to
correct me on this: it's been quite awhile since I looked at the doxygen
source)

I'm not sure Synopsis is a more flexible than Doxygen. Sure, you can have other parsers. But as far as I can see from the diagrams, the nodes in the syntax tree is limited to constructs found in C++. This might be a problem. With Doxygen it is possible to document anything - its own user manual is written with Doxygen, and that isn't anything like C++.

The core Synopsis AST does define node types which are C++ centric, but, Python being as dynamic as it is, this isn't much of a problem. Since Synopsis uses the GoF Visitor Pattern to traverse ASTs, it wouldn't be hard to reflect into the visitor and see if it is equipped to deal with the new node type and act accordingly. All that being said, the existing node types, for the most part, map to D concepts nicely. For instance, Scope nodes have a type, which is used to store whether a scope is a 'namespace', 'struct', 'class', or what have you. This means that, for instance, you could write a TemplateBlock node which extends the Class node and behaves in like a class whose type is 'template'. (or skip the subclassing altogether) With respect to your second point, the Doxygen manual almost *is* C. (it's almost completely comrised of block comments) The only reason it don't pass through a compiler is its use of the doxygen \verbatim and \endverbatim commands. -- andy
Aug 04 2004
parent "Martin M. Pedersen" <martin moeller-pedersen.dk> writes:
"Andy Friesen" <andy ikagames.com> skrev i en meddelelse
news:cero34$khm$1 digitaldaemon.com...
 This means that, for instance, you could write a TemplateBlock node
 which extends the Class node and behaves in like a class whose type is
 'template'. (or skip the subclassing altogether)

Then I have learned that much :-)
 With respect to your second point, the Doxygen manual almost *is* C.
 (it's almost completely comrised of block comments) The only reason it
 don't pass through a compiler is its use of the doxygen \verbatim and
 \endverbatim commands.

Yes, but it is used to document concepts not related to C++ syntax. Regards, Martin
Aug 04 2004