[Pasdoc-main] [ pasdoc-Patches-2055087 ] delete/ignore leading characters in comments

[SourceForge.net <no...@so...>]

Patches item #2055087, was opened at 2008-08-16 21:51
Message generated for change (Comment added) made by tobigun
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=304213&aid=2055087&group_id=4213

Please note that this message will contain a full copy of the comment thread,
including the initial issue submission, for this request,
not just the latest update.
Category: None
Group: None
Status: Open
Resolution: None
Priority: 5
Private: No
Submitted By: tobigun (tobigun)
Assigned to: Nobody/Anonymous (nobody)
Summary: delete/ignore leading characters in comments

Initial Comment:
Borland proposes a very (in my opinion) messy comment style in their styleguide. 

{ This is a comment.
  Second line. 
  Third line. }
MyVar: integer;
{ This is another comment.
  Second line.
  Third line. }
MyVar2: string;

It is difficult to separate comments from code, especially if code and comments change very often. Even with syntax-highlighting turned on its hard to distinguish both. Code folding might be a workaround but is not available on all editors.

Javadoc, Doxygen or phpDocumenter comments are much more easier to read and look much better.
There already was a feature request to support this style:
http://pasdoc.sipsolutions.net/WantedDeleteFirstChar

To be able to use such comments I changed the parser a little bit. The changes were applied to pasdoc 0.11.0 and submitted as a patch.

To ignore leading characters start pasdoc with the new command-line option --ignore-leading, e.g.:

pasdoc --ignore-leading=* my.pas

This will ignore all leading '*'-characters in '{' and '(*' comments, e.g. in

{*
 * Test
 *}

or 

{****************************
 * Test2
 ****************************}

Note that consecutive occurances of the character are ignored too (this corresponds to the Javadoc behavior).
The number of spaces preceding the character to ignore is irrelevant.

Trailing characters (e.g. '* MyTest *') are not removed from the comments, Javadoc does not handle them either.

As ignore-leading is a string-option you can even assign a string to it instead of a single character, e.g. '--ignore-leading=*!' although I would not encourage this.

The new option does not interfere with the --staronly or --marker options as these are handled before the characters are stripped.

Some further examples:

{**
 * --ignore-leading=* works with --staronly 
 *}

{###############################
 # --ignore-leading=#
 ###############################}

(*#?
  #? multiple chars can be ignored too 
  #? --ignore-leading=#?
  #?*)

{*
*   count of preceding whitespace does not matter
  * count of preceding whitespace does not matter
 **** consecutive characters are ignored too
    as in Javadoc not all lines have to start with the character
 *}

----------------------------------------------------------------------

>Comment By: tobigun (tobigun)
Date: 2008-08-16 21:56

Message:
Logged In: YES 
user_id=1751006
Originator: YES

Trailing whitespaces were removed in the examples after submitting them,
so they look a little strange.
They were supposed to be indented like this:
1{*
2 * Example
3 *}
File Added: ignore_leading_chars.zip

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=304213&aid=2055087&group_id=4213