At 6:30 PM +0100 30/1/03, Frank Heckenbach wrote:
Richard D. Jackson wrote:
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:
[snip]
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.
I think what Richard was driving at is that this level of annotation is to be done outside the code, after the fact. In the code, you just have the elements. Later you style the elements into some formatted structure. The formatted structure would be defined, say, in a style sheet (etc.) which would be separate from the code & initial doc output. Or are we missing eachother's points??? (Or agreeing and crossing on our explanations!?)
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.
I wasn't thinking of speed but independence of each module, ie. that documenting one module can go ahead independently of the other to a degree if the cross-referenced bits are accessed/checked/coordinated in some sensible manner. (Think of how given another module's definition components, you can (in principle!) develop a separate module, compiling against the definition module.) Put another way, I was probably thinking more along the lines where different (sub)projects need to refer to eachother, which as you commented is a somewhat different issue.
Anyway, this is probably too complex for this project...
Grant