Richard D. Jackson wrote:
On Mon, 2003-01-27 at 20:04, Frank Heckenbach wrote:
<big snip> > > > > Again I agree with you. I have only been able to find pasdoc but it was > > wrote for delphi/kylix/fpc which means the code may not be portable to > > gpc. It also has not been touched in a couple of years. I grabed a copy > > of the source and am going to take a look at getting it ported to gpc > > and add some things to it. For instance right now it will output HTML > > and Texi. The HTML part is OK but I will need to work on the Texi part > > and change it to texinfo as that is what is being used for gpc. > > 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 > should replace the interface copies in p/doc/generated. > > 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.
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