Re: Which documentation tool (DelphiDoc or Doc-o-Matic)


"Markus Spoettl (toolsfactory)" <nomail@xxxxxxxxxxxxxxxx> wrote in message
news:4681a38c@xxxxxxxxxxxxxxxxxxxxxxxxx
Jim Davis wrote:
- If you comment within the body of the source code, these will not be
extracted (regardless of tag prefix)

This has been getting thoughts in the past and while it is a rather simple
thing to add, it won't work most of the time. The basic question is if you
had an option like this, how would like like it to work? If you have a
function body that contains one comment only, things are pretty simple.
But what if you have a body with comments all over the place, commenting
individual blocks of instructions. Concatenating them together most likely
doesn't produce a meaningful result.

In delphi, there is only one comment possible per line of code.
Why Concatenate ?
Couldn't each comment just be placed on a seperate line in the document ?

It's been a while since I have visited doc-o-matic (v5.3) so I hope this
makes sense

Consider these requirements ....
Three levels of documentation
(1) General overview
pre-procedure Comments only
(2) Published Code View
pre-procedure Comments plus TYPE1 comments from within source.
TYPE1 comments could use the same tags as the pre-procedure Comments
(3) Developers Code View
pre-procedure Comments plus TYPE1 plus TYPE2 comments from within source.
TYPE2 comments would use a different tag to the pre-procedure Comments

Additionally, the option to include (or not) the actual source code for all
of the above views

here's a code example. the tags could of course be anything,
in this case,
TYPE1="//:" which is the same as the general comment tag, but doesn't need
to be
TYPE2="///"


// ====================================================
//: Description:
//: parses the lines the string list.
//: Arguments:
//: driver - The driver name string to be located.
//: Return Value:
//: TRUE if the driver name string could be found
//: FALSE not found.
//: Summary:
//: Checks to see if the scanner driver exists.
// ====================================================
function TfrmDensoS.doCheckDriver(driver: string): boolean;
var
var1: integer;
begin
Result := False;

//: Firstly we need to list the scanner drivers installed
doFillScannerList2(); /// replaced doFillScannerList() 07/07/2006 v2.1.89

//: test each item in the scanner list until found, or end
for var1 := 0 to frmScanProcess.sourceList.Items.Count - 1 do
begin
if (trim(frmScanProcess.sourceList.Items.strings[var1]) = trim(driver))
then
begin
Result := True;
exit;
end;
end;
end;

So the options relating to the body source would be
- include TYPE1 comments within body source [yes/no]
- include TYPE2 comments within body source [yes/no]
- include the body source [yes/no]

regards
Jim


.

Relevant Pages

  • Re: list subject
    ... Les Mikesell wrote: ... what I want it to do by default" regardless of how you want to do ... subscribe to is polite enough to identify itself with a tag and I don't ... recall ever seeing anyone complain about it - _ever_. ...
    (Fedora)
  • Re: OT: Doctor Assassinated in Church--Happy Now, Wingnuts??
    ... I want to tag him a terrorist because his politics, ideology and methods ... regardless of how much time you waste on apologia. ...
    (rec.gambling.poker)
  • Inserting text with a given tag
    ... How can I insert a piece of hardcoded text into a text widget such that it ... has a given tag from the start? ... Is there a better way which works regardless of newlines, ...
    (comp.lang.tcl)