Re: Source Text Tools

[Michael van Acken <mvacken@t-online.de>]

> > The really nice thing here is that this kind of data structure is very
> > useful for a large number of purposes.  Each of the following tools
> > can be built upon its information:
> 
> [...]
> 
> A number of these tools (printy printer, autodocumentation tool, code
> beautifier) are already implemented as part of VisualOberon. However
> they are hacked quick and dirty and their scanner/parser is very
> simple.

I doubt that your approach takes pragmas into account.  Or is quite as
flexible as building these tools on a single AST representation.

> > o To which declaration is a doc comment attached?  For procedures this
> > is simple, the comment is placed after the header but in front of the
> > first local declaration.  How is this handled for the other kinds of
> > declarations? 
> 
> The autodoc program has a little bit different aproach. Commands for an
> object are allways in front of an object. For module this means before
> the MODULE keyword, for procedures before the PROCEDURE keyword, for
> record before the record keyword. This worked well and did not uglified
> the source. I don't like the idea of putting the comment *after* the
> header (e.hg. after the PROCEDURE keyword or after the RECORD keyword)
> just for estethic reasons.

The description of a procedure usually contains references to its
parameter list.  Instead of doing forward references to the parameters
it's much more sensible to write the declaration first, and then
continue to give it meaning.

> If you also want to comment member variables, varibales constants etc...
> putting the comment before the keyword will not work, you have to put
> it after it. I strongly urge you to at least support this style, or I will
> have to change a huge amount fo sources to change this!

There are a lot of possibilities.  One possible implementation would
be to have a doc comment refer to the declaration it is part of, to
the previous, or the next declaration.  It would make sense to put
them in front of the declared name, on the other hand the same
argument as for procedures applies to all other declarations: first
write down the object in question, then start to explain it.

We have to agree how this should be done.  This decision should not be
based on any preferences because of existing code!

> > o Should there be special commands available to refer to other
> > declarations from within a comment?  E.g. a procedure doc comment
> > could refer to its parameter `foo' as @oparam{foo}, and to a type
> > `Bar' as @otype{Bar}.  This kind of reference tags allow consistency
> > checks (does the referenced declaration exist? is it of the correct
> > kind?) and permit to insert hyper-links when translating to HTML.
> 
> The problem with this aproch is, that you end implementing all keyword
> html or latex has. Tables and list will soon per to be nice stuff
> implemented. You can restrict yourself to a *very* limited set of
> options or drop the idea of makeing your own language and use an
> existing one. for autodoc I planed to yuse SGML together with the
> SGML-Tools. This will allow you a huge number of formatting stuff while
> beeing able to generate a huge number of document types without doing
> it all for yourself.

Doc comments don't have to be perfect.  There is no reason to put a
full range of formatting commands into them.  Doc comments are far to
restricted as that this approach would make sense.  If they are to
appear in a printed manual some form of manual intervention is always
necessary to get things right.  You might take a texinfo file
generated from doc comments, but you would never put it e.g. in the
OOC Reference Manual.  DCs are just a crutch.  The question is: What
should be included to make them a useful crutch?

> I'm sory that this mean that my selfwritten tools will be droped. But
> your aproach is of course the better one. But as told above I hope that
> the final solution will enable me to change tools without changing the
> whole source tree.

What do you expect?  The whole OOC libs would need a rewrite, too.  So
stop whining ;-)

-- mva