Preferred LotusScript comment style
As previously mentioned I'm looking into starting development of LotusScript.doc version 2 and for that I'm also rethinking how comments are written when writing LotusScript. In version 1 of LotusScript.doc I have only supported a LotusScript'ified version of the Javadoc syntax which meant that only the following comment syntax is considered valid:
'/** ' * This is my comment for the DoStuff sub-routine. ' */ Public Sub DoStuff() ... End SubComments of this kind can be placed inside or outside of code constructs (class, sub, function etc.) and will be picked up by LotusScript.doc accordingly. Apart from this you can write a description for a design element by using the lsdoc_description() sub-routine. This is the equivalent of the package.html from javadoc. Normally it would be used like this:
Private Sub lsdoc_description %REM %END REM End Sub
For LotusScript.doc v. 2 I would like to make this more flexible and support multiple commenting schemes so I'm thinking:
- "How do you comment your LotusScript?"
- Do you comment using %REM sections?
- Do you comment inside or outside the sub/function/class etc.?
- How do you document the design element it self?
I would really appreciate any input...
Re: Preferred LotusScript comment style
Hi Mikkel,
we use the following style in classes:
'/**
' * Class comment.
' */
Public Class XYZ
'/**
' * Method comment.
' */
Public Sub DoStuff()
...
In "normal" functions and sub we comment inside:
Public Sub DoStuff()
'/**
' * Sub comment.
' */
...
I personally do not like the
Private Sub lsdoc_description()
and would prefer a comment block in the Options section.
Thomas
http://www.assono.de/blog.nsf/
Re: Preferred LotusScript comment style
Hi Mikkel,
we are using the LSDoc style for commenting (for obvious reasons :-) ).
However we used to use %rem as it is much more convenient, e. g. when inserting additional lines in a comment (as we have no Eclipse inserting the javadoc syntax automatically).
I'd prefer to comment inside functions/subs (currently supported) and classes/methods (currently not supported). It helps for copy and paste operations.
I also would prefer the comment block in the Options sections as stated above (I do not like the lsdoc_description, which is easily overlooked when a human being is reading the code ;-) ).
Hans-Peter
However we used to use %rem as it is much more convenient, e. g. when inserting additional lines in a comment (as we have no Eclipse inserting the javadoc syntax automatically).
I'd prefer to comment inside functions/subs (currently supported) and classes/methods (currently not supported). It helps for copy and paste operations.
I also would prefer the comment block in the Options sections as stated above (I do not like the lsdoc_description, which is easily overlooked when a human being is reading the code ;-) ).
Hans-Peter
Re: Preferred LotusScript comment style
Hi Mikkel,
I would prefer the LSDoc comment to be inside a methode.
Public Class XYZ
'/**
' * Class comment.
' */
Public Sub DoStuff()
'/**
' * Method comment.
' */
...
This is mainly because I use LSClassBuddy / NotesHound Class Navigator to navigate inside the classes and they jump just to the start of the method. With the current comment style (comments outside of the method) I have to scroll up again to see the LSDoc comment.
First I thought about using a comment style using %REM lsdoc.But with %REM there is no way to indent the comment for methods. Which would make it harder to read.
Public Class XYZ
%REM lsdoc
Class comment.
%END REM
Public Sub DoStuff()
%REM lsdoc
Method comment.
%END REM
...
Re: Preferred LotusScript comment style
Ideas:
1.
2.
1.
%REM lsdoc @param foo Integer %END REMAnything that you type after the REM is part of the comment. So, if you put "lsdoc" after it, it can denote that this particular comment is in lsdoc format, and should be processed. You could also use "%REM lsdoc_description" for that particular block, so that people can put it wherever they feel comfortable.
2.
'' '@author Brian '@param blap Integeror
'' '@author Brian '@param blap Integer ''This is less typeheavy than the apos-plus-javadoc format, and it's a bit more intuitive for me. You can end with either the next '' that you run into, or the first non-comment line.
Re: Preferred LotusScript comment style
Hi Mikkel,
I am currently setting up lsdoc and bumped into a question that I hope you could help me with.
When adding a database to the lotusscript.doc configuration database and running the build; all design elements are visible in the html-documentation except for agents and script libraries built in Java. Maybe this is true for simple action agents and formula agents as well, haven't checked.
What I wonder first is if I missed some adjustment and if not I think it would be nice to list all design elements despite that lsdoc won't work for them. It would be great to at least be able to give a short overall description for them or else you need another way to comment and maintain the documentation for these design elements.
Thanks for a great tool!
I am currently setting up lsdoc and bumped into a question that I hope you could help me with.
When adding a database to the lotusscript.doc configuration database and running the build; all design elements are visible in the html-documentation except for agents and script libraries built in Java. Maybe this is true for simple action agents and formula agents as well, haven't checked.
What I wonder first is if I missed some adjustment and if not I think it would be nice to list all design elements despite that lsdoc won't work for them. It would be great to at least be able to give a short overall description for them or else you need another way to comment and maintain the documentation for these design elements.
Thanks for a great tool!
Preferred LotusScript comment style - need to have....
In the release 2, if it is possible to implement @see parameter to understand the subroutines/function linking within the script library/across script library without the need for implementing them as classes, that will be really helpful as we have our code implemented without any classes. As of now, we are not able to make @see in one function to be linked to another in the same script library or any other script library.