Re: [orion-dev] Happy about JS Doc?

[John Arthorne <John_Arthorne@xxxxxxxxxx>]

> Christophe Cornu/Ottawa/IBM@IBMCA 
> Sent by: orion-dev-bounces@xxxxxxxxxxx
> Are you using a particular flavor of JSDoc - this one here http://
> en.wikipedia.org/wiki/JSDoc ? Can you confirm you're happy with it
> and have no plan to switch to another format any time soon?

I think the jsdoc syntax is the defacto standard here.
Personally I think it is fine, although it is not very well specified and
in some cases it looks like there are many different ways to document similar
relationships. We may want to restrict ourselves to some useful subset
of the full jsdoc syntax and ignore some of the more esoteric ones (@description,
@example, etc).

> Which data types do you use for the @param { }? Do you have a list
> somewhere? String, Number, Boolean...

We haven't documented that. I think initially we should
use the return values of "typeof". I have entered a bug to document
this and make our usage consistent:

https://bugs.eclipse.org/bugs/show_bug.cgi?id=341172

> I'm thinking it'd be nice to align our own JS
code in RTC to use the
> same JS Doc used in Orion.
> Also, if the data type information is used consistently, it may be
> used as a hint by future tooling to provide some refactoring/search
> capabilities similar to JDT in Java code.

Yes. There are already tools out there that leverage
the type info from jsdoc, such as Google Closure and JSDT.

John