Re: Synopsis as documentation tool

Roman Yakovenko wrote:
> On 12/12/05, Stefan Seefeld <[email protected]> wrote:
> 
>>Roman Yakovenko wrote:
>>
>>>1. How do I specify project name?
>>
>>What is a project ?
> 
> 
> Good question. I am going to create documentation to 2 my projects:
> pygccxml and pyplusplus (http://www.language-binding.net/ )
> 
> Both projects written in Python and consist from few packages.

Ok. For python packages it might make sense to offer such a whole package
processing option. Patches are welcome !

>>>2. How do I tell Synopsis to work on whole package recursively?
>>
>>I deliberately avoided putting this kind of functionality into synopsis,
>>as that requires dependency management, something that is much better dealt with
>>by build tools such as 'make'.
> 
> 
> Okey, I understand the answer, and now I have an other question:
> How I create complete set of documentation for whole project? Do
> Synopsis has some
> "merge" functionality?

Yes, synopsis has some processors useful for 'linking', i.e. combining
ASTs from multiple source files.
(http://synopsis.fresco.org/docs/Tutorial/pipeline.html)

>>>3. What is the special syntax for comments\documentation string Synopsis uses?
>>
>>http://synopsis.fresco.org/docs/Tutorial/comments.html
> 
> 
> Yes, I saw this page. It says nothing about Python

Right. There are two different aspects to parsing comments: the first
is about how to recognize a comment is meant to be used as documentation.
That is only useful for languages such as C and C++, where ordinary
comments are used. In Python documentation is directly obtained from
the builtin __doc__ members.
The second aspect is the actual format of the string. Synopsis supports
for example java tags, so you may use them with your python code.
There are other styles (such as ReST), but they require other comment
parsers to be written.
If you want to try out synopsis' current builtin processors, I'd suggest
you use the JavaTags processor.

>>>4. How do I specify in documentation string the type of variable\argument?
>>>    ( I would like to have some link to the variable class definition
>>>in generated documentation )
>>
>>I'm not sure I understand what you are asking. You can always explicitely
>>insert links using something like '@see'. The type of a parameter is
>>obtained by inspecting the source code, not the comment, so you shouldn't
>>duplicate that information.
> 
> 
> Not in my case. :-)

Right. :-)
But then, you don't really want to document a type, but a precondition
('the first argument is expected to inherit from X, or to provide attributes
  y and z...'), right ?

>>>I understand that the best way to use Synopsis is to write my own
>>>Synopsis script,
>>>as is shown here http://synopsis.fresco.org/docs/Tutorial/script.html.
>>>But I would like to evaluate it first.
>>
>>Scripting is useful when you want to fine-tune the processing. For
>>simple cases the 'synopsis' application should be enough.
> 
> 
> I prefer to write some script, because this way it is much easier to integrate
> documentation generation in build process.

Yep.

Regards,
		Stefan