myfaces-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Werner Punz <werner.p...@gmail.com>
Subject Re: [trinidad] javascript documentation using jsdoc
Date Tue, 10 Jul 2012 07:25:29 GMT
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 <blake.sullivan@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
>>
>>
>




Mime
View raw message