You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@myfaces.apache.org by Leonardo Uribe <lu...@gmail.com> on 2012/07/05 14:59:19 UTC
[trinidad] javascript documentation using jsdoc
Hi
I tried to add this to trinidad-impl pom.xml:
<profiles>
<profile>
<id>generate-assembly</id>
<build>
<plugins>
<plugin>
<groupId>org.apache.myfaces.buildtools</groupId>
<artifactId>myfaces-jsdoc-plugin</artifactId>
<version>1.0-beta-1</version>
<executions>
<execution>
<id>attach-jsdoc</id>
<goals>
<goal>jar</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>
</profiles>
It is the same we use in myfaces core to generate javascript doc. The
good news is it works. We could add it as a report to generate it when
the site is build or include it as a jar.
But before do that, we need to add the proper jsdoc annotations.
Unfortunately, I get lost in the pattern used to annotate classes.
Does anybody knows which are the used code conventions in that part?.
For example in TrPanelPopup for example:
function TrPanelPopup()
{
//define object properties
this._content = false;
this._trigger = false;
this._centered = false;
this._modal = false;
this._visible = false;
}
TrPanelPopup.prototype.getContent = function()
What is prototype? the body of the class?.
I think with the work already done to generate the jsdoc in myfaces
core, generate the same info for trinidad is easy, but obviously jsdoc
annotations are a little bit tricky.
regards,
Leonardo Uribe
Re: [trinidad] javascript documentation using jsdoc
Posted by Werner Punz <we...@gmail.com>.
Hi Leo, also look at the myfaces core, I use the the jsdoc annotations
extensively to describe our classes and methods.
I am hiding the prototype construct there in favor of java like
inheritance but I use the meta descriptions, for example:
* @class
* @name Messages_de
* @extends myfaces._impl.i18n.Messages
* @memberOf myfaces._impl.i18n
*/
_MF_CLS(_PFX_I18N + "Messages_de", myfaces._impl.i18n.Messages,
/** @lends myfaces._impl.i18n.Messages_de.prototype */
{
This is a class myfaces._impl.Messages_de which extends
myfaces._impl.i18n.Messages
Problem there is jsdoc wont pick up the definitions in this case
automatically (it probably will if you use straight prototype
definitions) so I am giving it a helper push here by giving it some meta
information
* @class
* @name Messages_de
* @extends myfaces._impl.i18n.Messages
* @memberOf myfaces._impl.i18n
class
the name of the class
which class it extends
and which namespace it is member of
Since the methods and instance vars are described in a map I have to
give jsdoc a helping hand there as well
/** @lends myfaces._impl.i18n.Messages_de.prototype */
means that all definitions in the following map are mapped to
myfaces._impl.i18n.Messages_de.prototype
Not sure if you will need that in Trinidad since it seems to use raw
prototype functionality and jsdoc is quite good at picking those things
up, but i just wanted to add this info, in case you need it.
Werner
Am 06.07.12 11:01, schrieb Leonardo Uribe:
> Hi Blake,
>
> Yes that's exactly what I was looking for. So
> TrPanelPopup.prototype.getContent defines a non static method for
> thePopup.getContent(), the function TrPanelPopup() is the constructor
> and TrPanelPopup.staticGetContent is an static method from class
> TrPanelPopup. With that info, it shouldn't be hard to add the
> necessary annotations and generate the javascript documentation.
>
> regards,
>
> Leonardo Uribe
>
> 2012/7/5 Blake Sullivan <bl...@oracle.com>:
>> Leonardo,
>>
>> I'm not sure what you are asking. Are you asking what "prototype" means in
>> JavaScript? If that is what you are asking, then the quickie answer is that
>> Javascript uses template-based inheritance. Every JS Object has a prototype
>> property pointing to the instance that this JS Object will delegate to.
>> Some JS frameworks simulate class-based inheritance by creating an instance
>> representing a class and then making that instance the prototype of all of
>> the instances of that "class". Similarly a "subclass" would have it's
>> superclass as its prototype.
>>
>> Putting this together:
>>
>>
>> function TrPanelPopup()
>> {
>> //define object properties
>> this._content = false;
>> this._trigger = false;
>> this._centered = false;
>> this._modal = false;
>> this._visible = false;
>> }
>>
>> Is a constructor.
>>
>> new TrPanelPopup() would create an instance of TrPanelPopup.
>>
>> TrPanelPopup.prototype.getContent = function()
>>
>>
>> Is assigning the getContent() function to the prototype of instances created
>> through new TrPanelPopup(). getContent() ends up being similar to an
>> instance method.
>>
>> You can also create something like a static method, like so:
>>
>> TrPanelPopup.staticGetContent = function()
>>
>>
>> Notice the lack of the prototype. Callers would refer to this method (var
>> myContent = TrPanelPopup.staticGetContent()) directly rather than through an
>> instance:
>>
>> var thePopup = new TrPanelPopup();
>> var theContent = thePopup.getContent();
>>
>> -- Blake Sullivan
>>
>>
>> On 7/5/12 5:59 AM, Leonardo Uribe wrote:
>>>
>>> Hi
>>>
>>> I tried to add this to trinidad-impl pom.xml:
>>>
>>> <profiles>
>>> <profile>
>>> <id>generate-assembly</id>
>>> <build>
>>> <plugins>
>>> <plugin>
>>> <groupId>org.apache.myfaces.buildtools</groupId>
>>> <artifactId>myfaces-jsdoc-plugin</artifactId>
>>> <version>1.0-beta-1</version>
>>> <executions>
>>> <execution>
>>> <id>attach-jsdoc</id>
>>> <goals>
>>> <goal>jar</goal>
>>> </goals>
>>> </execution>
>>> </executions>
>>> </plugin>
>>> </plugins>
>>> </build>
>>> </profile>
>>> </profiles>
>>>
>>> It is the same we use in myfaces core to generate javascript doc. The
>>> good news is it works. We could add it as a report to generate it when
>>> the site is build or include it as a jar.
>>>
>>> But before do that, we need to add the proper jsdoc annotations.
>>> Unfortunately, I get lost in the pattern used to annotate classes.
>>>
>>> Does anybody knows which are the used code conventions in that part?.
>>> For example in TrPanelPopup for example:
>>>
>>> function TrPanelPopup()
>>> {
>>> //define object properties
>>> this._content = false;
>>> this._trigger = false;
>>> this._centered = false;
>>> this._modal = false;
>>> this._visible = false;
>>> }
>>>
>>> TrPanelPopup.prototype.getContent = function()
>>>
>>> What is prototype? the body of the class?.
>>>
>>> I think with the work already done to generate the jsdoc in myfaces
>>> core, generate the same info for trinidad is easy, but obviously jsdoc
>>> annotations are a little bit tricky.
>>>
>>> regards,
>>>
>>> Leonardo Uribe
>>
>>
>
Re: [trinidad] javascript documentation using jsdoc
Posted by Leonardo Uribe <lu...@gmail.com>.
Hi Blake,
Yes that's exactly what I was looking for. So
TrPanelPopup.prototype.getContent defines a non static method for
thePopup.getContent(), the function TrPanelPopup() is the constructor
and TrPanelPopup.staticGetContent is an static method from class
TrPanelPopup. With that info, it shouldn't be hard to add the
necessary annotations and generate the javascript documentation.
regards,
Leonardo Uribe
2012/7/5 Blake Sullivan <bl...@oracle.com>:
> Leonardo,
>
> I'm not sure what you are asking. Are you asking what "prototype" means in
> JavaScript? If that is what you are asking, then the quickie answer is that
> Javascript uses template-based inheritance. Every JS Object has a prototype
> property pointing to the instance that this JS Object will delegate to.
> Some JS frameworks simulate class-based inheritance by creating an instance
> representing a class and then making that instance the prototype of all of
> the instances of that "class". Similarly a "subclass" would have it's
> superclass as its prototype.
>
> Putting this together:
>
>
> function TrPanelPopup()
> {
> //define object properties
> this._content = false;
> this._trigger = false;
> this._centered = false;
> this._modal = false;
> this._visible = false;
> }
>
> Is a constructor.
>
> new TrPanelPopup() would create an instance of TrPanelPopup.
>
> TrPanelPopup.prototype.getContent = function()
>
>
> Is assigning the getContent() function to the prototype of instances created
> through new TrPanelPopup(). getContent() ends up being similar to an
> instance method.
>
> You can also create something like a static method, like so:
>
> TrPanelPopup.staticGetContent = function()
>
>
> Notice the lack of the prototype. Callers would refer to this method (var
> myContent = TrPanelPopup.staticGetContent()) directly rather than through an
> instance:
>
> var thePopup = new TrPanelPopup();
> var theContent = thePopup.getContent();
>
> -- Blake Sullivan
>
>
> On 7/5/12 5:59 AM, Leonardo Uribe wrote:
>>
>> Hi
>>
>> I tried to add this to trinidad-impl pom.xml:
>>
>> <profiles>
>> <profile>
>> <id>generate-assembly</id>
>> <build>
>> <plugins>
>> <plugin>
>> <groupId>org.apache.myfaces.buildtools</groupId>
>> <artifactId>myfaces-jsdoc-plugin</artifactId>
>> <version>1.0-beta-1</version>
>> <executions>
>> <execution>
>> <id>attach-jsdoc</id>
>> <goals>
>> <goal>jar</goal>
>> </goals>
>> </execution>
>> </executions>
>> </plugin>
>> </plugins>
>> </build>
>> </profile>
>> </profiles>
>>
>> It is the same we use in myfaces core to generate javascript doc. The
>> good news is it works. We could add it as a report to generate it when
>> the site is build or include it as a jar.
>>
>> But before do that, we need to add the proper jsdoc annotations.
>> Unfortunately, I get lost in the pattern used to annotate classes.
>>
>> Does anybody knows which are the used code conventions in that part?.
>> For example in TrPanelPopup for example:
>>
>> function TrPanelPopup()
>> {
>> //define object properties
>> this._content = false;
>> this._trigger = false;
>> this._centered = false;
>> this._modal = false;
>> this._visible = false;
>> }
>>
>> TrPanelPopup.prototype.getContent = function()
>>
>> What is prototype? the body of the class?.
>>
>> I think with the work already done to generate the jsdoc in myfaces
>> core, generate the same info for trinidad is easy, but obviously jsdoc
>> annotations are a little bit tricky.
>>
>> regards,
>>
>> Leonardo Uribe
>
>
Re: [trinidad] javascript documentation using jsdoc
Posted by Blake Sullivan <bl...@oracle.com>.
Leonardo,
I'm not sure what you are asking. Are you asking what "prototype" means
in JavaScript? If that is what you are asking, then the quickie answer
is that Javascript uses template-based inheritance. Every JS Object has
a prototype property pointing to the instance that this JS Object will
delegate to. Some JS frameworks simulate class-based inheritance by
creating an instance representing a class and then making that instance
the prototype of all of the instances of that "class". Similarly a
"subclass" would have it's superclass as its prototype.
Putting this together:
function TrPanelPopup()
{
//define object properties
this._content = false;
this._trigger = false;
this._centered = false;
this._modal = false;
this._visible = false;
}
Is a constructor.
new TrPanelPopup() would create an instance of TrPanelPopup.
TrPanelPopup.prototype.getContent = function()
Is assigning the getContent() function to the prototype of instances
created through new TrPanelPopup(). getContent() ends up being similar
to an instance method.
You can also create something like a static method, like so:
TrPanelPopup.staticGetContent = function()
Notice the lack of the prototype. Callers would refer to this method
(var myContent = TrPanelPopup.staticGetContent()) directly rather than
through an instance:
var thePopup = new TrPanelPopup();
var theContent = thePopup.getContent();
-- Blake Sullivan
On 7/5/12 5:59 AM, Leonardo Uribe wrote:
> Hi
>
> I tried to add this to trinidad-impl pom.xml:
>
> <profiles>
> <profile>
> <id>generate-assembly</id>
> <build>
> <plugins>
> <plugin>
> <groupId>org.apache.myfaces.buildtools</groupId>
> <artifactId>myfaces-jsdoc-plugin</artifactId>
> <version>1.0-beta-1</version>
> <executions>
> <execution>
> <id>attach-jsdoc</id>
> <goals>
> <goal>jar</goal>
> </goals>
> </execution>
> </executions>
> </plugin>
> </plugins>
> </build>
> </profile>
> </profiles>
>
> It is the same we use in myfaces core to generate javascript doc. The
> good news is it works. We could add it as a report to generate it when
> the site is build or include it as a jar.
>
> But before do that, we need to add the proper jsdoc annotations.
> Unfortunately, I get lost in the pattern used to annotate classes.
>
> Does anybody knows which are the used code conventions in that part?.
> For example in TrPanelPopup for example:
>
> function TrPanelPopup()
> {
> //define object properties
> this._content = false;
> this._trigger = false;
> this._centered = false;
> this._modal = false;
> this._visible = false;
> }
>
> TrPanelPopup.prototype.getContent = function()
>
> What is prototype? the body of the class?.
>
> I think with the work already done to generate the jsdoc in myfaces
> core, generate the same info for trinidad is easy, but obviously jsdoc
> annotations are a little bit tricky.
>
> regards,
>
> Leonardo Uribe