[Pasdoc-main] [ pasdoc-Patches-3485263 ] Added support for HelpInsight style comments

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

Patches item #3485263, was opened at 2012-02-07 01:54
Message generated for change (Comment added) made by kambi
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=304213&aid=3485263&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: Closed
>Resolution: Accepted
Priority: 5
Private: No
Submitted By: VCejka (vcejka)
Assigned to: Michalis Kamburelis (kambi)
Summary: Added support for HelpInsight style comments

Initial Comment:
Support for Delphi /MS VS style somments in form /// <tag> comment </tag> added. Internally they are translated to pasdoc tags. Tags supported in this version (see TParser.ExpandHelpInsightDescriptions):
summary ->@abstract
param -> @param
returns -> returns
exception -> @raises
permission -> @permission
c -> @code
code -> @preformatted
b -> @bold
i -> @italic
u -> @underline
br -> @br
ul -> @unorderedList
ol -> @orderedList
li -> @item
remark -> plain text
remarks -> plain text
comment -> plain text

New token type TOK_COMMENT_HELPINSIGHT added to PasDoc_Tokeniker.TTokenType, and also corresponding TOKEN_TYPE_NAMES string and TokenCommentTypes set member. Detection of new comment style is added to TTokenizer.ReadCommentType3, translation is launched from TParser.GetLastComment.


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

>Comment By: Michalis Kamburelis (kambi)
Date: 2012-02-08 01:53

Message:
Applied, thank you for the patch!

See the latest SVN source code (trunk). Your patch was applied in revision
1308. I added note to ChangeLog. (Say your full name, or fill it in
SourceForge account, if you want me to change the "(by VCejka)" to use your
full name :)

- Documented on http://pasdoc.sipsolutions.net/WritingDocumentation
- Added testcase tests/ok_helpinsight_comments.pas, it's HTML output is
visible here:
http://pasdoc.sourceforge.net/correct_tests_output/html/ok_helpinsight_comments/ok_helpinsight_comments.html

I adjusted regexp code to use FPC's RegExpr unit (in FPC >= 2.6.0). Delphi
code (under $ifndef FPC) should work the same (but please check, as I do
not own Delphi).

A little problem was found by testsuite: you replace always, even when
author didn't use /// comment. Consider code like this:

  { Returns HTML line break, <br>. }
  function LibeBreak: string;

  { My docs. @html(Some text using HTML tags<br>blah blah<br>) }
  procedure Foo;

In both these cases, <br> *must not* be replaced with @br. The general rule
in pasdoc comments is that < and > do not have any special meaning (only @
is special), this must not be broken in comments not using ///. I fixed it
already (in SVN revision 1310) by LastCommentHelpInsight variable, and
ExpandHelpInsightDescriptions is only run when LastCommentHelpInsight =
true.


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

Comment By: VCejka (vcejka)
Date: 2012-02-07 03:40

Message:
Thank you very much for such fast answer. You are right with regular
expressions. I'm not using FPC, so I'm not used thinking about that.

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

Comment By: Michalis Kamburelis (kambi)
Date: 2012-02-07 02:49

Message:
I forgot to add: I will actually test it and adjust to FPC and apply
tomorrow.

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

Comment By: Michalis Kamburelis (kambi)
Date: 2012-02-07 02:47

Message:
Thank you. I quickly looked at the patch, looks very clean and should apply
without any problems. The only small thing that will have to be fixed is to
replace RegularExpressions unit and class with FPC equivalent under {$ifdef
FPC}, I can take care of it.

I understand the official docs about this feature are here:
http://delphi.wikia.com/wiki/Help_insight .

I'm not sure do I like implementing this using regular expressions, but
it's certainly much shorter and simpler than anything I can otherwise
propose now :)

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

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