Re: Synopsis as documentation tool

Roman Yakovenko wrote:
> On 12/12/05, Stefan Seefeld <[email protected]> wrote:
> 
>>Hi Roman,
> 
> 
>>Did you read the tutorial at http://synopsis.fresco.org/docs/Tutorial/index.html ?
>>While far from complete, it should definitely get you started. Please don't
>>hesitate if you have specific questions.
> 
> 
> Yes I do. This tutorial is really far from being complete:
> 
> 1. How do I specify project name?

What is a project ?

> 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'.

> 3. What is the special syntax for comments\documentation string Synopsis uses?

http://synopsis.fresco.org/docs/Tutorial/comments.html

> 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.

> 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.

Regards,
		Stefan