An important announcement from the founder of property-bee.com: The future of Property Bee is assured.

JSDoc Toolkit

An area to discuss the development and technical aspects of the toolbar

JSDoc Toolkit

Postby Beerhunter on Sun Oct 18, 2009 4:43 pm

I've been trying out JSDoc Toolkit, in the hope that it will make it easier to follow the source, give a better overview of the design and make me document the code.

JsDoc Toolkit is an application, written in JavaScript, for automatically generating template-formatted, multi-page HTML (or XML, JSON, or any other text-based) documentation from commented JavaScript source code.


Overall I'm impressed with the initial results and have comitted some documentation changes, so JSDoc Toolkit is supported.

You can see the output (for Revision 41) here

Generating the documentation locally
If you wish to generate the documentation locally;

1) Install JSDoc Toolkit

2) Create a batch file "generate_documentation.bat";

Code: Select all
cd c:\jsdoc_toolkit-2.3.0\jsdoc-toolkit
java -jar jsrun.jar app\run.js -a -d=C:\property-bee\sourceforge\2.0\doc -r=3 -t=templates\jsdoc -v C:\property-bee\sourceforge\2.0\trunk\
pause


where
* "c:\jsdoc_toolkit-2.3.0\jsdoc-toolkit" is the path to your JSDoc toolkit
* "C:\property-bee\sourceforge\2.0\doc" is the path to output the documentation to
* "C:\property-bee\sourceforge\2.0\trunk\" is the path you the source code you want to document

3) Double click on the batch file to generate the documentation.

Documenting the source
To document the source code wrap the comments as follows;

Code: Select all
/**
 *
 *
 */


The tags are very much like JavaDoc, see the Tag Reference

I'll be adding more comments, but as a starting point all files/classes are correctly recognised and indexed :D
User avatar
Beerhunter
Site Admin
 
Posts: 1788
Joined: Tue Jan 22, 2008 12:05 am

Re: JSDoc Toolkit

Postby Squidward on Mon Oct 19, 2009 1:02 am

PB_Location

PB_Location Functor to obtain the location attribute from a node, and pass the attribute string through a child functor.

Hmm, I thought that might happen (repeated class name) but I was hoping against it. I'll clean it up. They should have called that tag '@description', not '@class', because it would read better in the source code (as eg. '@param' introduces a parameter name and description, so '@class' should introduce a class name and description, or just '@description' introduce the description).

Oh wait, there is a tag called @description... [tries stuff out]... nah, it doesn't do the trick. I rejiggled the comments I made earlier into the least unpleasant layout I could find which still gets picked up by JsDoc. (Now maybe it's too spaced out.)

JsDoc's a bit inflexible about it. In C++ with Doxygen I currently like to do this, which I know may be slightly unusual

Code: Select all
void myFunction(int arg1, int arg2)
/** Do some stuff.
 *
 *  @param arg1 First argument.
 *  @param arg2 Second argument.
 */
{

to get the function name on top and eliminate the question of repeating it in the comment. JsDoc doesn't roll with that at all.

Here's some other thoughts about these sorts of documentation systems, not necessarily apropos of Property Bee, just current musings from my miiind.

There's a danger of repeating yourself - I've caught myself writing things a bit like

Code: Select all
Append an item to a list

@param item
  the item that will be appended to the list
@param list
  the list that the item will be appended to
@returns
  the list with the item appended onto it

and felt a bit silly.

When commenting pb_rules.js I was thinking, a person reads the paragraph at the top first, eg.

Code: Select all
//  Functor to tidy up a string,
//  and pass the tidied string through a child functor.
//

(which - for a function - describes what it does) and then goes on to read the per-parameter comments in that context, so all you need for the functor argument is

Code: Select all
//  fn          (type: function) Child functor.

since there's only one child functor involved in the situation, there's no need to add anything more. The briefer the better, while still relating it to the original description.

However, for specifics about the use of the parameters - say you've got two strings which could be confused

Code: Select all
Search for a string inside another string

@param searchString
  string to be searched
@param findString
  string to search for

Per-parameter comments are great for this kind of "which way round?" question.

Specifics relating to just the one parameter, like if it has a complicated format, also naturally go under @param:

Code: Select all
@param {string} propertyDetails
  The property details as a comma-seperated list of field names and values,
  eg. "name1: value1, name2: value2, name3: value3" etc

--

I don't think you should feel obligated to tag every code item but if you've decided you need to comment something, it's good to have a formal way of doing it (moreso in view of Javascript's rather implicit syntax).

I think, unless it's a library, you're probably not going to use the output; if it's some external component you're utilising in another project whose internals you're not interested in, an HTML guide is invaluable; but if the source files are actually in the same project, I would more likely just open them directly and look at the tags.

But, I was impressed when I first hit the doc page you generated, so maybe I'm changing my mind (I wrote some of this post a few days ago and didn't want to remove all of the wise-ass sounding phrases :)). But another thing, it seems like JsDoc doesn't let you filter the list by file, or otherwise put things in groups... you just get all of the functions in the project on one page, regardless of importance, which seems bad.

(This isn't meant to be critical; I had to see you set up JsDoc before forming some of these opinions. I don't have any suggestions for alternative doc systems, which work in javascript, which I've actually used. I'm happy to carry on writing JsDoc comments if others like it or aren't bothered either way by such a small thing. :))
Squidward
 
Posts: 34
Joined: Mon Jun 09, 2008 1:28 pm

Re: JSDoc Toolkit

Postby Beerhunter on Mon Oct 19, 2009 9:46 am

Squidward wrote:Hmm, I thought that might happen (repeated class name) but I was hoping against it. I'll clean it up. They should have called that tag '@description', not '@class', because it would read better in the source code (as eg. '@param' introduces a parameter name and description, so '@class' should introduce a class name and description, or just '@description' introduce the description).

Oh wait, there is a tag called @description... [tries stuff out]... nah, it doesn't do the trick. I rejiggled the comments I made earlier into the least unpleasant layout I could find which still gets picked up by JsDoc. (Now maybe it's too spaced out.)

JsDoc's a bit inflexible about it. In C++ with Doxygen I currently like to do this, which I know may be slightly unusual

Code: Select all
void myFunction(int arg1, int arg2)
/** Do some stuff.
 *
 *  @param arg1 First argument.
 *  @param arg2 Second argument.
 */
{

to get the function name on top and eliminate the question of repeating it in the comment. JsDoc doesn't roll with that at all.


I think there's a subtle difference between @class and @description, eg

Code: Select all
/**
 *   @class This is a class
 */
function PB_Class() {
}

/**
 *   @description What is this?
 */
function PB_Something() {
}


I suspect PB_Something defaults to being a global function.

Squidward wrote:Here's some other thoughts about these sorts of documentation systems, not necessarily apropos of Property Bee, just current musings from my miiind.

There's a danger of repeating yourself - I've caught myself writing things a bit like

Code: Select all
Append an item to a list

@param item
  the item that will be appended to the list
@param list
  the list that the item will be appended to
@returns
  the list with the item appended onto it

and felt a bit silly.


Yup, found myself deleing bits like that

Squidward wrote:When commenting pb_rules.js I was thinking, a person reads the paragraph at the top first, eg.

Code: Select all
//  Functor to tidy up a string,
//  and pass the tidied string through a child functor.
//

(which - for a function - describes what it does) and then goes on to read the per-parameter comments in that context, so all you need for the functor argument is

Code: Select all
//  fn          (type: function) Child functor.

since there's only one child functor involved in the situation, there's no need to add anything more. The briefer the better, while still relating it to the original description.


I agree, infact I'd go futher and say the param 'fn' should really be named 'childFunctor' then the description contains all the info, and the param doesn't need documenting.

Squidward wrote:However, for specifics about the use of the parameters - say you've got two strings which could be confused

Code: Select all
Search for a string inside another string

@param searchString
  string to be searched
@param findString
  string to search for

Per-parameter comments are great for this kind of "which way round?" question.

Specifics relating to just the one parameter, like if it has a complicated format, also naturally go under @param:

Code: Select all
@param {string} propertyDetails
  The property details as a comma-seperated list of field names and values,
  eg. "name1: value1, name2: value2, name3: value3" etc

--


Completely agree with the above.

I'd also add;

* a good thing (esp in javascript code) is describing the parameter types, which is very useful I feel

* documenting limitations / obscure gotchas

* sometimes describing what a function does is easier with an example, rather than words.

Squidward wrote:I don't think you should feel obligated to tag every code item but if you've decided you need to comment something, it's good to have a formal way of doing it (moreso in view of Javascript's rather implicit syntax).


I agree, tho initially also part of the process of me documenting whats in my head / highlighting known problems etc so that that info is available to everyone else.

Squidward wrote:I think, unless it's a library, you're probably not going to use the output; if it's some external component you're utilising in another project whose internals you're not interested in, an HTML guide is invaluable; but if the source files are actually in the same project, I would more likely just open them directly and look at the tags.


Yes, its not a library as such, but I'd like to move in that kind of direction, ie

* a core "library" (actually app is a better description) which doesn't know how to display/parse information or have any user interface, but has documented interfaces to allow...

* library "users" (actually add-ons is a better description), ie rules, styles, the toolbar/sidebar etc which extend the core app to do something useful.

Squidward wrote:But, I was impressed when I first hit the doc page you generated, so maybe I'm changing my mind (I wrote some of this post a few days ago and didn't want to remove all of the wise-ass sounding phrases :)). But another thing, it seems like JsDoc doesn't let you filter the list by file, or otherwise put things in groups... you just get all of the functions in the project on one page, regardless of importance, which seems bad.

(This isn't meant to be critical; I had to see you set up JsDoc before forming some of these opinions. I don't have any suggestions for alternative doc systems, which work in javascript, which I've actually used. I'm happy to carry on writing JsDoc comments if others like it or aren't bothered either way by such a small thing. :))


One thing potentially very useful about JSDoc is that it's template driven (see the templates directory under jsdoc-toolkit), so theres the ability to add new views / add ability to search / change the layout etc, or even generate output in a completely different format, whether its easy or not is a different matter!

I think the key things are

* comments can be useful, but writing comments for the sake of it isn't

* generating the html files may not be all that useful at the moment but having a defined format (which is machine readable) for comments is probably a good idea

* if/when the project structure is more core app/add-ons, the documentation of those interfaces will become important and hence the html doc may become more relevent, esp if we support add-ons to the property-bee add-on :D
User avatar
Beerhunter
Site Admin
 
Posts: 1788
Joined: Tue Jan 22, 2008 12:05 am

Re: JSDoc Toolkit

Postby Squidward on Mon Oct 19, 2009 6:35 pm

Beerhunter wrote:
Squidward wrote:When commenting pb_rules.js I was thinking, a person reads the paragraph at the top first, eg.

Code: Select all
//  Functor to tidy up a string,
//  and pass the tidied string through a child functor.
//

(which - for a function - describes what it does) and then goes on to read the per-parameter comments in that context, so all you need for the functor argument is

Code: Select all
//  fn          (type: function) Child functor.

since there's only one child functor involved in the situation, there's no need to add anything more. The briefer the better, while still relating it to the original description.


I agree, infact I'd go futher and say the param 'fn' should really be named 'childFunctor' then the description contains all the info, and the param doesn't need documenting.

Yeah, totally. As it happens I tend to avoid abbreviations in my own code (maybe to the point of ridiculousness; I'm swinging back towards single letters now for loop variables).


Beerhunter wrote:
Squidward wrote:I don't think you should feel obligated to tag every code item but if you've decided you need to comment something, it's good to have a formal way of doing it (moreso in view of Javascript's rather implicit syntax).


I agree, tho initially also part of the process of me documenting whats in my head / highlighting known problems etc so that that info is available to everyone else.

A funny thing to me is that my adding comments to pb_rules.js was partly a way for me to get familiar with its contents as a user of it in the first place - and I wonder that if I came to code which was already 'perfectly' commented, whether it wouldn't ironically be harder for me to get into, there being nothing for me to do!

Now that's crazy talk and I don't believe it yet... but when people say "it's harder to read code than it is to write it" I do agree and wonder about that.

Beerhunter wrote:
Squidward wrote:Yes, its not a library as such, but I'd like to move in that kind of direction, ie

* a core "library" (actually app is a better description) which doesn't know how to display/parse information or have any user interface, but has documented interfaces to allow...

* library "users" (actually add-ons is a better description), ie rules, styles, the toolbar/sidebar etc which extend the core app to do something useful.

Yeah, you want to keep it all good and well structured and sliceable like bangers for today's hyper-mashable world. :)
Squidward
 
Posts: 34
Joined: Mon Jun 09, 2008 1:28 pm

Re: JSDoc Toolkit

Postby s-p on Mon Oct 19, 2009 6:46 pm

Squidward wrote:A funny thing to me is that my adding comments to pb_rules.js was partly a way for me to get familiar with its contents as a user of it in the first place - and I wonder that if I came to code which was already 'perfectly' commented, whether it wouldn't ironically be harder for me to get into, there being nothing for me to do!

Now that's crazy talk and I don't believe it yet... but when people say "it's harder to read code than it is to write it" I do agree and wonder about that.


I think it all depends on the individual user and their familiarity with the language they're being exposed to. But given that we all have different coding styles, it's certainly possible that you're going to be far more comfortable with you're own code than having to interpret someone else's.
Scott
s-p
 
Posts: 125
Joined: Mon Jun 09, 2008 10:20 pm

Re: JSDoc Toolkit

Postby Beerhunter on Mon Oct 19, 2009 9:44 pm

s-p wrote:
Squidward wrote:A funny thing to me is that my adding comments to pb_rules.js was partly a way for me to get familiar with its contents as a user of it in the first place - and I wonder that if I came to code which was already 'perfectly' commented, whether it wouldn't ironically be harder for me to get into, there being nothing for me to do!

Now that's crazy talk and I don't believe it yet... but when people say "it's harder to read code than it is to write it" I do agree and wonder about that.


I think it all depends on the individual user and their familiarity with the language they're being exposed to. But given that we all have different coding styles, it's certainly possible that you're going to be far more comfortable with you're own code than having to interpret someone else's.


I think your both right;

* Reading code, you think your understanding but the reality your just looking at it. Its the interaction with the code that really matters; documenting it or using it gains a lot more knowledge (perhaps I should get everyone else to document my code ;))

* Different coding styles can be an off-putting... but the comment on being "comfortable" is really key I feel. Its the ability to recognise the concepts behind the code which comes back to coding style; its like trying understand something written in grammatically correct English or pigeon English - both maybe expressing the same concepts, but one is much easier to grasp the underlying message.

It's an interesting topic, and beleive writing software is very much like like writing a story, there are characters / interactions / subplots / hidden themes; however often the time constrains / ability to rewrite chapters the message can get muddled.
User avatar
Beerhunter
Site Admin
 
Posts: 1788
Joined: Tue Jan 22, 2008 12:05 am


Return to Development

Who is online

Users browsing this forum: No registered users and 7 guests

cron