On Tue, 2003-01-28 at 22:41, Frank Heckenbach wrote:
Richard D. Jackson wrote:
On Mon, 2003-01-27 at 20:04, Frank Heckenbach wrote:
<snip>
I've made some plans for such a utility, in particular some features required, and some ideas for the syntax.
My main goal would be (unlike some -- I don't know if all -- of the other utilities), to have the syntax as simple and readable as possible, e.g. to use paired quotes (like `foo') for markup (which would be @samp{foo} in texi). The purpose would explicitely *not* be to have a complete layout system (such as TeX; I think already texi is not), but to focus on the common things. (There can always be an escape mode for the occasional exception.)
In the end, the existing comments in the unit interfaces, where they exists, should be accepted with few modifications, and the output
If to get what I/we want means that the existing comments need to change I'm more than willing to do it. The only unit that will be difficult or time consuming to do will the the RTS unit. But still I willing to do the work to get good well formated and cross referanced doc's.
should replace the interface copies in p/doc/generated.
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 return type/description ( may or may not need this ) paramiter code example header ( by this I mean module header or description ) referance index this for later cross referance ect... 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. POD on the other had basicly has taken the stance that this is all you get and if you don't like it write your own output module to get what you want. This means that it has sacrificed flexablity for conformance to a standard. And do you know something Perl code is some of the best documented code out there. Which is why I want to follow the perl lead but mostlikly not the format itself. Mostly becase POD does contain some format/layout command in it as well. I really don't want to worry about format/layout when I document code.
What I intend to do before writing any code is to write a specification which I will run by here for comments before writing any code. As I would rather have input and some kind of agrement that it is what we want.
If there is some real interest, I could write my ideas (which now are just some random notes).
pasdoc, the tool I'm looking at was modeled after javadoc syntax. I personaly prefer more of a perl POD type syntax. Other words I would prefer to keep it simple. complex stuff just ends up not being used. the simple stuff that works gets used.
And yes I would love to see what your ideas are. As I would really prefer to know what everyone wants before starting to work on it.
I don't know POD, but I agree to the "keep it simple" principle. :-)
I just noticed that I started such a thing long time ago. I'm attaching it. But it's just a skeleton yet -- the whole markup stuff is missing. My ideas are put in the top comment of the file (which is longer than the rest of the code ;-). It may already be more complex than what's really needed.
The most difficult bits (and the ones where the program will be most helpful) will probably be, besides the extracting of the comments in the first place, the generation of cross-references.
See further down...
I may actualy just end up rewriting it from scratch as it is using quite a few custom class that duplicate units gpc already has and I would prefer to use the ones gpc provides verses costom ones.
BTW, I don't quite see where such a utility would need classes and collections and all that stuff at all, but then, I'm only a moderate OOP follower ...
OOP would make some things easer to do. For instance in the case of pasdoc it creates a document class that handles all of the parsing of the source files. Then a output class is pluged into the doc class to make the finished docs. Yes you can do something simular with out using OOP but OOP provides a more eligant solution to the problem. It also makes it easy to plug new output backends in with out affecting the main body of code.
I agree to the last point. I'm not sure about the former. I don't see a need for "polymorphism" there, neither for multiple instances -- if the program will support translation of multiple files (not really necessary IMHO since it will usually be run from the Makefile, and it can just as well call it once per file -- in fact, it would do so, aynway, to keep track of dependencies), but even then they would be processed one after another, not simultaneously ...
With only a single instance and without polymorphism, an object class is basically the same as a unit/module.
Frank
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. And for doing this OOP will be very helpfull. 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 ....."