Richard D. Jackson wrote:
What I envioson is more of a tag syntax verses a complete layout system. By tag I mean something that indicates that something is: Author name Module version copyright notice description
These are usually global (per module), currently contained in a comment at the top. Ideally, the tool would get them from there using the existing information. E.g.:
: { Some utility routines for compatibility to some units available : for BP, like some `Turbo Power' units.
Title
: Copyright (C) 1998-2003 Free Software Foundation, Inc.
Copyright notice (keyword "Copyright" :-).
: Authors: Prof. Abimbola A. Olowofoyeku African_Chief@bigfoot.com : Frank Heckenbach frank@pascal.gnu.de
Author name(s) (keyword "Author(s)").
[Further description (could be put right after the title if it makes things easier)]
: This file is part of GNU Pascal. : : GNU Pascal is free software; you can redistribute it and/or modify
License (could be put together with the copyright notice if it makes things easier).
return type/description ( may or may not need this ) paramiter
As for the syntax, these are clear from the declaration, therefore should not require further commenting.
I think it should be enough to write the declaration in the "Synopsis" part. A Pascal programmer ought to know what the declaration means and how to use it.
The semantics of each parameter and the return value (if any), of course, should be described in the text, but I'm not sure we need any formalities for that.
code example
Yep.
header ( by this I mean module header or description )
These are the things mentioned above, aren't they?
referance
Yes, quite important. As I wrote in my program's comments, I'd prefer to make them as easily as possible, e.g., <foo> will write the identifier foo in the text, but also put it in the references section. It might seem a small issue, but not having to write the thing twice (in the text and the references) is more comfortable and will probably encourage people to use many references. :-)
Of course, adding more references explicitly (`@seealso' in my example) should also be possible.
But not a whole lot of stuff. Leave formating and structure up to the output code. This is how POD, JavaDoc ( core stuff that is ) and a few others do. That way if you don't like the output you can write your own output generator that will format it the way you want. Core Doxygen does this as well but becasue the backend dictates the output form/layout it has had many output generaters created for it. But I think its down fall is that it does allow the programmer to use or embed form/layout stuff for specific output generaters which means the programmer spends can spend too much time trying to do some special form/layout verses just writing the doc.
I basically agree. Though I think there is some amount of markup we need. E.g., to mark identifiers (see above, with references for identifiers mentioned besides the current ones), and to mark sections of code etc. E.g., the description of gpc.pas:CanRead currently says:
[...] This is similar to `not EOF (aFile)', but [...]
So the `not EOF (aFile)' part should be marked in some way to avoid confusion -- preferably (to me) `...' in the input and @samp{...} in the texi output.
Also, it *might* be useful to write emphasis sometimes. In plain text formats which don't provide for this, people will often use *...* for it, so a tool could just as well convert it to proper emphasis in the output.
First the question I would have is what is the target application of the documenter? If for only documenting single monolithic units then a single pass ( single file ) tool would do the job. But on the other hand if you want to handle multi-module/unit applications that need to beable to cross link the documention and or have a unified cross-referance amogst all the code modules then what you really want to do is process all of the files in a single pass.
Not necessarily. If you're worried about cross-references, Texinfo handles them already (see below).
One other thing I would like for it to do besides output the documentation is to output a cross referance list so that other modules can referance the doc if needed. For instance lets say I'm writing a string utility unit wouldn't it be nice if I could referance the RTS with in my doc's and actualy have a working link to the RTS doc for a paricular function/procedure verses something like this " see these functions in the RTS documentation ....."
As you might know, texi has references that refer to "nodes" by name. If we generally make each node's name the same as the identifier being described, we can refer to every identifier in the current or another module the same way. (The scheme would break if there are several identifiers of the same name in different modules. This is allowed, but honestly, who would do so -- within one project! I think we can ignore this. ;-)
So the translation would run like this (which is basically what is done now for the GPC manual, where the part of the new tool is taken by a simple copying of the interface):
foo.pas -> foo.texi bar.pas -> bar.texi baz.pas -> baz.texi myproj.texi (contains the main menu and possibly other documentation) {myproj,foo,bar,baz}.texi -> myproj.{info,html,dvi,ps,pdf,...}
It's different when you want to refer to things from other projects (e.g., you write documentation for your own code and want to refer to the GPC manual directly). BTW, that's no different whether the tool will translate single or multiple files, since different projects are translated separately, anyway. Actually, all that's required then is to get the name of the other documentation file -- the texi reference would then look like `@ref{WriteLn,,,gpc}' instead of `@ref{WriteLn}'.
To do this automatically, the cross reference list you suggested might be useful. I.e., while translating the GPC documentation, this list is produced and stored somewhere, and when translating the documentation of another project, it could use this list to find out which identifiers should have their references pointing to the GPC documentation.
Grant Jacobs wrote:
Don't include format per se, but include some style class information like 'header' 'text' etc so that it can be appropriately formatted later.
I'd prefer sections to headers. The difference may be small, but rather than inserting headers here and there, this will structure the documentation. I suppose that smaller units will not need sections at all, but for larger ones they could be useful. One hierarchy level should be enough, though.
Its a good point, but I think processing all the files in a single pass has exactly the same flaw as compiling code in the same fashion. The interface/implementation approach was developed for that reason.
I don't know if speed is a real concern here, but still I'd prefer the separate translation approach, too.
Frank