Re: Synopsis as documentation tool

On Mon, Dec 12, 2005 at 08:51:56AM +0200, 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?
>2. How do I tell Synopsis to work on whole package recursively?
>3. What is the special syntax for comments\documentation string Synopsis uses?
>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 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.

In a tiny C++ package, i have the following in my Makefile, just to give
you an idea, eventually:

# documentation, cross-reference
hdr := $(wildcard *.hh)
syn := $(patsubst %.hh, %.syn, $(hdr))
html: $(syn)
	synopsis -f HTML -Wf,title="'snmp-cxx Documentation'" -o $@ $^
%.syn: %.hh
	synopsis -p Cxx -I. -l SSDComments,Previous \
	-Wp,preprocess,cppflags="'$(CXXFLAGS)'" -o $@ $<

1) is/was -Wf,title="string"
One of '-' or ',' wasn't allowed in string back when i looked last
as the argument parse wouldn't count open/close quotes and
double-quotes.
2) see e.g. $(hdr)
3) see synopsis -l