Received: by 10.52.240.229 with SMTP id wd5mr10864911vdc.8.1340647254648; Mon, 25 Jun 2012 11:00:54 -0700 (PDT) X-BeenThere: jsdoc-users@googlegroups.com Received: by 10.221.13.130 with SMTP id pm2ls1975397vcb.6.gmail; Mon, 25 Jun 2012 11:00:53 -0700 (PDT) Received: by 10.52.68.141 with SMTP id w13mr400509vdt.18.1340647253292; Mon, 25 Jun 2012 11:00:53 -0700 (PDT) Date: Mon, 25 Jun 2012 11:00:52 -0700 (PDT) From: Kristian To: jsdoc-users@googlegroups.com Cc: Kristian Message-Id: <61960116-28c2-4662-a0a6-f01c82830685@googlegroups.com> In-Reply-To: <99F13965-C7DA-4A4F-917C-0C0D887D73BA@gmail.com> References: <58b43cf6-bc19-4ab1-b887-717639cd4e42@googlegroups.com> <99F13965-C7DA-4A4F-917C-0C0D887D73BA@gmail.com> Subject: Re: Documenting non-static properties MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="----=_Part_21_24247576.1340647252757" ------=_Part_21_24247576.1340647252757 Content-Type: multipart/alternative; boundary="----=_Part_22_10433906.1340647252757" ------=_Part_22_10433906.1340647252757 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 7bit Thanks for the quick response, Michael! I tried your two suggestions and omitting the @name tag works. However, this class is defined within a module, so I added the @exports tag. /** * @constructor * @param {Number} radius * @exports Circle */ var Circle = function(radius) { // Body }; .... return Circle; Now all of the appropriate doc is created except for the the constructor details I read http://usejsdoc.org/tags-exports.html, but it does not seem to cover the case of using both @exports tag with @constructor to make this happen . In general, if I have a single class defined in each of my modules, what is the best way to document the class within the module? I think the main problem I'm running into is trying to refer to the module and the class by the same name. Thanks for you help, Kristian On Saturday, June 23, 2012 9:40:06 AM UTC-4, Michael Mathews wrote: > > Try removing the "@name Circle" bit. To see why that matters, check out > the docs for @name... > > http://code.google.com/p/jsdoc-toolkit/wiki/TagName > > "Be warned though, by using the @name tag you are telling JsDoc Toolkit > to ignore the surrounding code and to treat your documentation comment in > isolation. This can be a powerful technique because it allows you to write > documentation for objects that are not visible in the code itself (or are > obscure for some reason)." > > In other words the function named "Circle," which appears immediately > after the doc comment with the @name, is ignored by JSDoc, exactly as if it > had no comment. That's kinda the point of @name; If you didn't want the > function to be ignored by JSDoc you wouldn't use @name in the comment. > > By the way JSDoc 3 has a new tag called @alias, which is intended to work > the same as @name but *without* ignoring the surrounding code, sort of > the best of both worlds when you need to give a different name but you want > that new name applied to the the code that exists. Note, however that you > don't need either @name or @alis in your example because the name in the > code is already what you want it documented to be. > > Michael Mathews > micm...@gmail.com > > > > On 22 Jun 2012, at 20:33, Kristian wrote: > > What is the best way to document non-static properties using JsDoc3? The > @property tag " is intended for simple collections of static properties, > it does not allow you to provide @examples or similar complex information > for each property, just the type, name and description." > > For a simple example, if I have something like the following: > > /** > * @name Circle > * @constructor > * @param {Number} radius > */ > function Circle(radius) { > /** > * Property documentation for x - note default value > */ > this.x = 0; > > /** > * Property documentation for y - note default value > */ > this.y = 0; > > /** > * Property documentation for radius > */ > this.radius = radius; > } > > How can I get the documentation for properties x, y, and radius to appear > and include the information in provided @see, @type, @default, and @example > tags? > > Trying to force the doc by using a @memberof tag gets it to show up, but > marks it as static and includes the "this" qualifier, which is not what I'm > aiming for. > > Thanks, > > Kristian > > -- > You received this message because you are subscribed to the Google Groups > "JSDoc Users" group. > To view this discussion on the web visit > https://groups.google.com/d/msg/jsdoc-users/-/mhVXo82fRDYJ. > To post to this group, send email to jsdoc-users@googlegroups.com. > To unsubscribe from this group, send email to > jsdoc-users+unsubscribe@googlegroups.com. > For more options, visit this group at > http://groups.google.com/group/jsdoc-users?hl=en. > > > ------=_Part_22_10433906.1340647252757 Content-Type: text/html; charset=utf-8 Content-Transfer-Encoding: quoted-printable Thanks for the quick response, Michael!  I tried your two suggestions = and omitting the @name tag works. However, this class is defined within a m= odule, so I added the @exports tag. 

 /**
     * @constructor
    &nbs= p;* @param {Number} radius
   = ;            * @exports Circle 
  &nbs= p;  */
    var Circle =3D function(radius) {<= /div>
          // Body
  =   };
          =     ....
            &nbs= p; return Circle;
 
Now all of the appropriate doc is c= reated except for the the constructor details I read http://usejsdoc.org/tags-exports.html,= but it does not seem to cover the case of using both @exports tag with @co= nstructor to make this happen .

In general, if I have a single class= defined in each of my modules, what is the best way to document the class = within the module? I think the main problem I'm running into is trying to r= efer to the module and the class by the same name.

Thanks for you he= lp,

Kristian



<= br>On Saturday, June 23, 2012 9:40:06 AM UTC-4, Michael Mathews wrote:
Try removing the "@name Circle" bit. To see why that matters, check out th= e docs for @name...


"Be warned though, by using the @name=  tag you are telling JsDoc= Toolkit to ignore the surrounding code and to treat your documentation com= ment in isolation. This can be a powerful technique because it allows you t= o write documentation for objects that are not visible in the code itself (= or are obscure for some reason)."

In other words the function named "Circle," which appears immediately afte= r the doc comment with the @name, is ignored by JSDoc, exactly as if it had= no comment. That's kinda the point of @name; If you didn't want the functi= on to be ignored by JSDoc you wouldn't use @name in the  comment.

<= span style=3D"color:rgb(0,0,0);font-family:arial,sans-serif;font-size:13px;= font-style:normal;font-variant:normal;font-weight:normal;letter-spacing:nor= mal;line-height:16px;text-align:-webkit-auto;text-indent:0px;text-transform= :none;white-space:normal;word-spacing:0px;background-color:rgb(255,255,255)= ;display:inline!important;float:none">By the way JSDoc 3 has a new tag call= ed @alias, which is intended to work the same as @name but without ig= noring the surrounding code, sort of the best of both worlds when you need = to give a different name but you want that new name applied to the the code= that exists. Note, however that you don't need either @name or @alis in yo= ur example because the name in the code is already what you want it documen= ted to be.

Michael Mathews
m= icm...@gmail.com



On 22 Jun 2012, at 20:33, Kristian wrote:

What is the bes= t way to document non-static properties using JsDoc3? The @property tag " is intended for simple collections of stat= ic properties, it does not allow you to provide @examples or similar comple= x information for each property, just the type, name and description."

For a simple example, if I have something like the foll= owing:

    /**
     * @name= Circle
     * @constructor
   = ;  * @param {Number} radius
     */
=
    function Circle(radius) {
     =  /**
        * Property documentation f= or x - note default value
        */
        this.x =3D 0;

&= nbsp;      /**
        * Prope= rty documentation for y - note default value
     =   */
        this.y =3D 0;

       /**
        * Property documentation for radius
=         */
       &= nbsp;this.radius =3D radius;
    }

H= ow can I get the documentation for properties x, y, and radius to appear an= d include the information in provided @see, @type, @default, and @example t= ags? 

Trying to force the doc by using a @mem= berof tag gets it to show up, but marks it as static and includes the "this= " qualifier, which is not what I'm aiming for.

Tha= nks,

Kristian

--
You received this message because you are subscribed to the Google Groups "= JSDoc Users" group.
To view this discussion on the web visit https://groups.googl= e.com/d/msg/jsdoc-users/-/mhVXo82fRDYJ.
=20 To post to this group, send email to jsdoc-users@googlegroups.com.
To unsubscribe from this group, send email to jsdoc-users+unsubscribe@googlegroups.com.
For more options, visit this group at http://groups.google.com/g= roup/jsdoc-users?hl=3Den.

------=_Part_22_10433906.1340647252757-- ------=_Part_21_24247576.1340647252757--