Comments before methods

[sinaghino]

I'm using D2006 and I noticed the following behavior when a new method is automatically added to the code by using ctrl+shift+c key combination:

{
comment for procedure A}
procedure A;
begin
end;

{
comment for procedure C}
procedure B;
begin
end;

procedure C;
begin
end;

Originally I had procedure A and C, when I add procedure B as prototype and then use ctrl+shift+c to have Delphi automatically create the actual procedure in the implementation section, the procedure B is automatically created between A and C but the comments don't follow the right procedure. So, having comments before the actual procedure doesn't seem to be the standard in D2006, having comments between "procedure" and "begin" lines work ok, however, DelphiCodeToDoc does not recognize this location. Is it easy enough to add an option to select comments before or after the method? Thanks a lot, this change (if possible) will be howsome for us and a lot of other D2005/D2006 users.

[CCRDude]

I experience the same... adding a feature request to CodeGears Quality Central might be an idea, though you won't see any changes before Delphi 2022 then probably ;)
So I would vote for comments below the function header as well (just today tried if this is possible ;) )

[TridenT]

My previous replies here : https://sourceforge.net/forum/message.php?msg_id=4196580

Yes, I have the same issue on my projets ...

>>>So, having comments before the actual procedure doesn't seem to be the standard in D2006
I've never seen another way to do !

Writing comments between PROCEDURE and BEGIN keywords looks strange, i've never seen this, and it is not like the JavaDoc "standard".

So, for the moment, I will not add this possibility, but I will ask CodeGear about it, I'm sure they will answer me !
I'm sorry not to have a solution for this, I know it is very annoying.

CodeGear already had an open bug here :

http://qc.codegear.com/wc/qcmain.aspx?d=602

I will way anyone posting a feature request to wsork on it :o)

TridenT

[Erik De Laet]

Just for the record, I write all my comments between procedure and begin.
It's all a question of personal taste of course.

As in:
function HtmlB(const psValue:string):string;
{___________
|
| 'Html B'
|
| Returns the 'psValue' surrounded in a html-bold formatted syntax.
|___________}
begin
Result := '<b>'+ psValue + '</b>';
end;
function HtmlU(const psValue:string):string;
{___________
|
| 'Html U'
|___________}
begin
Result := '<u>'+ psValue + '</u>';
end;
function StrtoDateBE (const S:string):TDateTime;
{___________
|
| 'Str To Date BE'
|
| Converterts the string "s" (which is in the Belgian standard date format
| to a DateTime variable.
|___________}
var KeepDateSeparator : Char;
....

I used this system for years. This way, when you are browsing your source code, you don't look at the actual routine names anymore, but look at the nicely spaced versions (inside the comment box) in stead.
Sadly for me I can't use the DelphiCodeToDoc program unless I rewrite all of my units.
It would really help me if you should parse comments immediatly after a function or procedure line too.

[TridenT]

ok, there are multiple demands about this feature, I will work on it as soon as other major bugs are fixed.
I will keep you informed about it.

Thx for your explanation.

[Erik De Laet]

Hi,

While you are at it: it would be a very nice touch if you could call a dll (which we could write our self) passing the comments to be processed by you as parameters. That way we could pre-format the comment block from whatever format we like to the format you need (in my case, I would strip the box characters from the comments before you process the lines. That way I could still use my own style of comments, and still be able to use your doc generator.

[klatham]

I'll add my two cents here, and vote for comments inside the method/procedure/function.

TridenT, you are doing great work here, and I know you are using JAVADOC as your inspiration, but putting comments after the header is really closer to "the Pascal way". On the surface, it would appear to be a 50/50 call, and the original JAVADOC author picked his favourite way to do it. However putting it 'inside' the procedure implementation is more natural because you know the comment applies to that procedure and it not just generic comments in the source. And of course this makes it more foolproof for automated refactoring or even just cut and paste to move blocks of code from one unit to another.

Thanks for your good work on this.

[TridenT]

Yes, javaDoc is my inspiration, but DelphiCodeToDoc is design to be an open solution with many options.
So, i've heard all of you, I've received sufficient emails from users to improve the comment parser and allow comments 'inside' the procedure body.

I will keep you informed about this specification, and its implementation.

Thx all for your post.

TridenT

[Josh Kramer]

Any updates on the status of this feature? The projects I would like to use this on also only have comments between procedure and begin and not before the method.

Our project consists of over a couple million lines of code so updating the placement is not a realistic/desireable option, but this software looks like a promising way to quickly document our comments.

[TridenT]

Hi, a test version (v0.21beta.2) is out since few days and includes this feature.

See the following example.
You can download the dailybuild here :
http://trident.job.free.fr/delphicodetodoc/dailybuild/DelphiCodeToDoc.zip

Note : this is only a dailybuild version, without any translation nor the command-line version.

here is a list of the features and fixes :
Fixed redirection from console (hhc.exe) generates spurious string to log window
Fixed Exception with empty var section in class (Tracker 2488024)
Fixed no (htm) output generation when "ocClasses" is removed (Tracker 2487028)
Updated parser to support freepascal language (exponent *, operators)
Updated html output now in UTF8 format
======> * Added support for comments just after a procedure (between procedure headings and the BEGIN keyword)

So please, give me a feedback about this version if you are interested.
The next public version will be out in few days now (v0.22b).

procedure TNewClass.MyProc(const MyProcParam : integer);
{*-------------------------------------------
Comment MyProc !
@param MyProcParam Comment MyProcParam !
---------------------------------------------}
begin
// dummy
end;

procedure TNewClass.AnotherProc;
/// Comment AnotherProc !
begin
// dummy
end;

[Josh Kramer]

I'm trying out the build in the link provided, but it does not seem to be grabbing the comments between procedure headings and the BEGIN.

[TridenT]

Hi,

can you cut & paste an example of the commented source code (just few lines, one procedure for example) and also send me the project's config file (*.xml).
It works for every users by now, so maybe it is only a wrong configuration or writing ... or you've found a new bug ;)

[Josh Kramer]

Simple example:

function TFormTestForm.TestFunction(const TestString: string): string;
{Displays and returns the passed string}
begin
//display the string
ShowMessage(TestString);
//return the string
Result := TestString;
end;

[TridenT]

According to this comment style, here are the settings:

• 'Curly Prefix {' = #0 (empty)
• 'Skip first TAG line in comment block' = false
• 'Skip last TAG line in comment block' = false

Hope this will help you.

[TridenT]

Tell me if it ok for you !