jsdoc-user — Anything about JSDoc, including questions, bugs, requests for new features, ...

Re: [Jsdoc-user] Large files

[Michael M. <mi...@gm...>]

Hi Dave,

I have test cases for "the new Rhino one" (formally "JsDoc Toolkit")  
that work fine on source files with over 10,000 lines of code (which  
weighs in at about 200K) but beyond that, I admit, I haven't thought  
to try -- a 1.4MB sized JavaScript file would be extremely unusual I  
would think. Can you post it somewhere (maybe zipped) so that I can  
include it in a future test case (obviously *don't* send the actual  
file to the mailing list). I'd also be interested to know what memory  
is available on your computer.

One possible option that may help you is JsDoc Toolkit's ability to  
store it's documentation comments in a separate file from the source  
code. Of course JsDoc Toolkit isn't yet stable (expect a 1.0 release  
in July) and this option would require you to provide more explicit  
information in your documentation comments, but if file size is a  
concern it may be worth considering.

Regards,
Michael


On 6 May 2007, at 06:05, Dave Johnson wrote:

> Hey everyone,
>
> I am having a bit of trouble with large files in JSDoc. We have about
> a 1.4MB js file and JSDoc just stops part way through with no message.
> If we reduce the amount of code to about 800Kb it starts working
> again. I also made sure it was not just one problematic function or
> something like that. Although, I think it has been working in the past
> with large files and has now stopped working so any suggestions would
> be much appreciated.
>
> Any ideas?
>
> btw I tried the new Rhino one but it died pretty quickly on me.
>
> Cheers,
> Dave
>
> ---------------------------------------------------------------------- 
> ---
> This SF.net email is sponsored by DB2 Express
> Download DB2 Express C - the FREE version of DB2 express and take
> control of your XML. No limits. Just data. Click to get it now.
> http://sourceforge.net/powerbar/db2/
> _______________________________________________
> Jsdoc-user mailing list
> Jsd...@li...
> https://lists.sourceforge.net/lists/listinfo/jsdoc-user

[Jsdoc-user] Large files

[Dave J. <da...@ni...>]

Hey everyone,

I am having a bit of trouble with large files in JSDoc. We have about
a 1.4MB js file and JSDoc just stops part way through with no message.
If we reduce the amount of code to about 800Kb it starts working
again. I also made sure it was not just one problematic function or
something like that. Although, I think it has been working in the past
with large files and has now stopped working so any suggestions would
be much appreciated.

Any ideas?

btw I tried the new Rhino one but it died pretty quickly on me.

Cheers,
Dave

Re: [Jsdoc-user] License of jsdoc

[Michael M. <mi...@gm...>]

Hi,

You are correct that the latest stable release is JSDoc 1.x. It is  
licensed under the GNU General Public License (GPL).

This is listed here: http://sourceforge.net/projects/jsdoc

Regards,
Michael


On 6 Apr 2007, at 13:44, Matej Cepl wrote:

> Hi,
>
> trying to package jsdoc for Fedora/extras (still the jsdoc 1.*,  
> which is
> the only version which is considered truly stable, right?), and
> unfortunately I cannot found any license for jsdoc. I am afraid that
> Fedora won't accept a package without any license. Could you point  
> me to
> the one?
>
> Thanks,
>
> Matej Cepl
> -- 
> http://www.ceplovi.cz/matej/blog/, Jabber: ceplma<at>jabber.cz
> GPG Finger: 89EF 4BC6 288A BF43 1BAB 25C3 E09F EF25 D964 84AC
>
> Thank you for sending me a copy of your book; I'll waste no time
> reading it.
> -- Moses Hadas
>
>
>
> ---------------------------------------------------------------------- 
> ---
> Take Surveys. Earn Cash. Influence the Future of IT
> Join SourceForge.net's Techsay panel and you'll get the chance to  
> share your
> opinions on IT & business topics through brief surveys-and earn cash
> http://www.techsay.com/default.php? 
> page=join.php&p=sourceforge&CID=DEVDEV
> _______________________________________________
> Jsdoc-user mailing list
> Jsd...@li...
> https://lists.sourceforge.net/lists/listinfo/jsdoc-user

[Jsdoc-user] License of jsdoc

[Matej C. <mc...@re...>]

Hi,

trying to package jsdoc for Fedora/extras (still the jsdoc 1.*, which is
the only version which is considered truly stable, right?), and
unfortunately I cannot found any license for jsdoc. I am afraid that
Fedora won't accept a package without any license. Could you point me to
the one?

Thanks,

Matej Cepl
-- 
http://www.ceplovi.cz/matej/blog/, Jabber: ceplma<at>jabber.cz
GPG Finger: 89EF 4BC6 288A BF43 1BAB 25C3 E09F EF25 D964 84AC

Thank you for sending me a copy of your book; I'll waste no time
reading it.
-- Moses Hadas

Re: [Jsdoc-user] documenting a class?

[Michael M. <mi...@gm...>]

I'm on the verge of begging you to try JSDoc-2 now. The order of  
tags, custom or otherwise, is completely under your control. I  
understand if you don't have time to try a tool that is still in  
beta, but your feedback could in fact help us get to the final 1.0  
release that little bit faster. In any case JSDoc-2 will eventually  
be finalized (I expect in June/July), and I hope you'll find it will  
solve these issues.

Regards,
Michael

On 3 Apr 2007, at 19:25, Gabriel Reid wrote:

> Hi Kate,
>
>> Thank you both for your responses! Your information totally  
>> answered my
>> question. Also, thanks for helping me out the other week by  
>> showing me
>> how to create a custom @example tag. I'd still like to figure out  
>> a way
>> to ensure that the contents of this tag always appear AFTER all the
>> other tags. One of your emails said there is no way to enforce  
>> this and
>> that the only downside of a custom tag is that there's no telling  
>> where
>> the information will appear (in other words, the "example" text could
>> appear after the @returns info, it could appear before @returns, it
>> could appear after @throws - - there is no way to specify where the
>> example will appear). Is this true with all custom tags, or was this
>> just true for the sample code snippet that you provided to me:
>>
>
> Your understanding of custom tags in JSDoc is correct: there currently
> isn't a way of forcing the order in which they're rendered in the
> documentation.
>
> If you feel that this is something you'd like to use, I could  
> certainly
> look into improving this functionality in JSDoc. I've basically  
> left the
> original functionality as it is since I first wrote it, as there  
> hasn't
> ever been all that much interest in the custom tag construct as it
> currently stands.
>
> Regards,
>
>     Gabriel
>
> ---------------------------------------------------------------------- 
> ---
> Take Surveys. Earn Cash. Influence the Future of IT
> Join SourceForge.net's Techsay panel and you'll get the chance to  
> share your
> opinions on IT & business topics through brief surveys-and earn cash
> http://www.techsay.com/default.php? 
> page=join.php&p=sourceforge&CID=DEVDEV
> _______________________________________________
> Jsdoc-user mailing list
> Jsd...@li...
> https://lists.sourceforge.net/lists/listinfo/jsdoc-user

[Jsdoc-user] Fwd: documenting a class?

[Michael M. <mi...@gm...>]

Rest easy, I expect the @class tag to remain deprecated in JSDoc-2  
forever -- but it won't be removed. I do hope people appreciate how  
much effort is being made to maintain compatibility with not only  
JSDoc 1.x but also with ScriptDoc. And, of course, JSDoc 1.x is in no  
danger of disappearing. It and the baby will be safe in the bath for  
long into the future.

This does bring up another point, which is, far aside from any tool  
that parses JSDoc comments, what is the "Standard Definition" of  
JSDoc tags? I'd love to have a single definitive list of what tags  
there are and what they mean. I could just write one, but I don't see  
why anyone should care what my opinion is. More important, what are  
the opinions of the users? And what would the process be of  
collecting and distilling those opinions?

If anyone has any thoughts on how to manage such a discussion I'd be  
happy to hear them.

Regards,
Michael

On 3 Apr 2007, at 19:13, bru...@wa... wrote:

>
> Please don't throw out the baby with the bath water with regard to  
> Classes...
> While it is laudable to document the use of JavaScript programmed  
> in the spirit of JavaScript,
> don't forget that many of us ARE simply trying to parallel Java  
> language features (like Classes)
> and that is why we started using JsDoc in the first place!
> Don't take away our illusion that we really are using Java  
> classes. ;-)
> thanks, Bruce
> see..
> http://www.developer.com/lang/jscript/article.php/3657486
> http://www.polyglotinc.com/AJAXscratch/
>
> >The original design for JSDoc wasn't all that clever -- I just copied
> >"how Javadoc does it." Easy for Java programmers to understand but
> >slightly problematic for the rest of us because it abuses the idea of
> >the JavaScript language a bit.
> >
> >As you rightly ask, what is a "class" in JavaScript? JavaScript is a
> >prototype-based language without classes. However, you can think of
> >constructor functions as behaving like classes -- mostly. So
> >essentially any function you intend to invoke with the "new" keyword
> >would be called a "class" by JSDoc.
> >
> >To atone for this sin (it really has been bothering me), I've
> >deprecated the "@class" tag in JSDoc-2 in favor of the "@constructor"
> >tag, which hopefully will better reflect what JavaScript is  
> actually doing.
> ---------------------------------------------------------------------- 
> ---
> Take Surveys. Earn Cash. Influence the Future of IT
> Join SourceForge.net's Techsay panel and you'll get the chance to  
> share your
> opinions on IT & business topics through brief surveys-and earn cash
> http://www.techsay.com/default.php? 
> page=join.php&p=sourceforge&CID=DEVDEV________________________________ 
> _______________
> Jsdoc-user mailing list
> Jsd...@li...
> https://lists.sourceforge.net/lists/listinfo/jsdoc-user

Re: [Jsdoc-user] documenting a class?

[Gabriel R. <gab...@gm...>]

Hi Kate,

> Thank you both for your responses! Your information totally answered my
> question. Also, thanks for helping me out the other week by showing me
> how to create a custom @example tag. I'd still like to figure out a way
> to ensure that the contents of this tag always appear AFTER all the
> other tags. One of your emails said there is no way to enforce this and
> that the only downside of a custom tag is that there's no telling where
> the information will appear (in other words, the "example" text could
> appear after the @returns info, it could appear before @returns, it
> could appear after @throws - - there is no way to specify where the
> example will appear). Is this true with all custom tags, or was this
> just true for the sample code snippet that you provided to me:
> 

Your understanding of custom tags in JSDoc is correct: there currently
isn't a way of forcing the order in which they're rendered in the
documentation.

If you feel that this is something you'd like to use, I could certainly
look into improving this functionality in JSDoc. I've basically left the
original functionality as it is since I first wrote it, as there hasn't
ever been all that much interest in the custom tag construct as it
currently stands.

Regards,

    Gabriel

Re: [Jsdoc-user] documenting a class?

[<bru...@wa...>]

Please don't throw out the baby with the bath water with regard to 
Classes...
While it is laudable to document the use of JavaScript programmed in the 
spirit of JavaScript,
don't forget that many of us ARE simply trying to parallel Java language 
features (like Classes)
and that is why we started using JsDoc in the first place!
Don't take away our illusion that we really are using Java classes. ;-)
thanks, Bruce
see..
http://www.developer.com/lang/jscript/article.php/3657486
http://www.polyglotinc.com/AJAXscratch/

>The original design for JSDoc wasn't all that clever -- I just copied 
>"how Javadoc does it." Easy for Java programmers to understand but 
>slightly problematic for the rest of us because it abuses the idea of 
>the JavaScript language a bit.
>
>As you rightly ask, what is a "class" in JavaScript? JavaScript is a 
>prototype-based language without classes. However, you can think of 
>constructor functions as behaving like classes -- mostly. So 
>essentially any function you intend to invoke with the "new" keyword 
>would be called a "class" by JSDoc.
>
>To atone for this sin (it really has been bothering me), I've 
>deprecated the "@class" tag in JSDoc-2 in favor of the "@constructor" 
>tag, which hopefully will better reflect what JavaScript is actually 
doing.

Re: [Jsdoc-user] documenting a class?

[Rodrigues, K. <kro...@ne...>]

Michael and Gabriel -

Thank you both for your responses! Your information totally answered my
question. Also, thanks for helping me out the other week by showing me
how to create a custom @example tag. I'd still like to figure out a way
to ensure that the contents of this tag always appear AFTER all the
other tags. One of your emails said there is no way to enforce this and
that the only downside of a custom tag is that there's no telling where
the information will appear (in other words, the "example" text could
appear after the @returns info, it could appear before @returns, it
could appear after @throws - - there is no way to specify where the
example will appear). Is this true with all custom tags, or was this
just true for the sample code snippet that you provided to me:

=20

$METHOD_ATTRS_MAP{example} =3D

        sub {

            my $ex =3D $_[0][0];

            return "<div style=3D'background: #CCCCCC; border: dashed =
2px;
padding: 12px; width: 70%'> <code>$ex</code></div>";

        };=20

=20

thanks so much,

kate

=20

-----Original Message-----
From: Michael Mathews [mailto:mi...@gm...]=20
Sent: Monday, April 02, 2007 11:19 PM
To: jsd...@li...
Cc: Rodrigues, Kate
Subject: Re: [Jsdoc-user] documenting a class?

=20

Hi Kate,

=20

The original design for JSDoc wasn't all that clever -- I just copied
"how Javadoc does it." Easy for Java programmers to understand but
slightly problematic for the rest of us because it abuses the idea of
the JavaScript language a bit.

=20

As you rightly ask, what is a "class" in JavaScript? JavaScript is a
prototype-based language without classes. However, you can think of
constructor functions as behaving like classes -- mostly. So essentially
any function you intend to invoke with the "new" keyword would be called
a "class" by JSDoc.

=20

To atone for this sin (it really has been bothering me), I've deprecated
the "@class" tag in JSDoc-2 in favor of the "@constructor" tag, which
hopefully will better reflect what JavaScript is actually doing.

=20

Regards,

Michael

=20

=20

On 3 Apr 2007, at 02:19, Rodrigues, Kate wrote:





All -

=20

I was asked by someone in my group if, using JSDoc, I am going to
provide high level descriptions at the top of each "class" page (similar
to the figure below). As I've stated to the group, I am new to
documenting JavaScript, so I'm not quite sure what constitutes a "class"
in JavaScript. If I'm documentation for JavaScript functions, objects,
and methods, which is considered the class? Based on your response,
which @ tag do I use within my JavaScript file to document a class?=20

=20

Thanks a million!

kate

=20

=20

<image001.jpg>

<image001.jpg>

------------------------------------------------------------------------
-

Take Surveys. Earn Cash. Influence the Future of IT

Join SourceForge.net's Techsay panel and you'll get the chance to share
your

opinions on IT & business topics through brief surveys-and earn cash

http://www.techsay.com/default.php?page=3Djoin.php&p=3Dsourceforge&CID=3D=
DEVDE
V_______________________________________________

Jsdoc-user mailing list

Jsd...@li...

https://lists.sourceforge.net/lists/listinfo/jsdoc-user

=20

Re: [Jsdoc-user] documenting a class?

[Michael M. <mi...@gm...>]

Hi Kate,

The original design for JSDoc wasn't all that clever -- I just copied =20=

"how Javadoc does it." Easy for Java programmers to understand but =20
slightly problematic for the rest of us because it abuses the idea of =20=

the JavaScript language a bit.

As you rightly ask, what is a "class" in JavaScript? JavaScript is a =20
prototype-based language without classes. However, you can think of =20
constructor functions as behaving like classes -- mostly. So =20
essentially any function you intend to invoke with the "new" keyword =20
would be called a "class" by JSDoc.

To atone for this sin (it really has been bothering me), I've =20
deprecated the "@class" tag in JSDoc-2 in favor of the "@constructor" =20=

tag, which hopefully will better reflect what JavaScript is actually =20
doing.

Regards,
Michael


On 3 Apr 2007, at 02:19, Rodrigues, Kate wrote:

> All =96
>
>
> I was asked by someone in my group if, using JSDoc, I am going to =20
> provide high level descriptions at the top of each =93class=94 page =20=

> (similar to the figure below). As I=92ve stated to the group, I am =20
> new to documenting JavaScript, so I=92m not quite sure what =20
> constitutes a =93class=94 in JavaScript. If I=92m documentation for =20=

> JavaScript functions, objects, and methods, which is considered the =20=

> class? Based on your response, which @ tag do I use within my =20
> JavaScript file to document a class?
>
>
> Thanks a million!
>
> kate
>
>
>
> <image001.jpg>
>
> <image001.jpg>
> ----------------------------------------------------------------------=20=

> ---
> Take Surveys. Earn Cash. Influence the Future of IT
> Join SourceForge.net's Techsay panel and you'll get the chance to =20
> share your
> opinions on IT & business topics through brief surveys-and earn cash
> http://www.techsay.com/default.php?=20
> page=3Djoin.php&p=3Dsourceforge&CID=3DDEVDEV____________________________=
____=20
> _______________
> Jsdoc-user mailing list
> Jsd...@li...
> https://lists.sourceforge.net/lists/listinfo/jsdoc-user

Re: [Jsdoc-user] Prototypical inheritence of built-in types creates entries for built-in types in class list

[Gabriel R. <gab...@gm...>]

Hi Bruce,

> Gabriel Reid wrote:
> >This is definitely a (new) bug; I'll try to have a fixed version
> >available by the end of the week. Thanks for pointing this out.
> >  
> Thanks for the speedy reply. I would try and offer a patch but I fear it 
> would take me longer to disentangle the perl than it would for you to 
> fix it (I'm not really familiar with perl)!

Ok, I've just released version 1.10.2 with this bug fixed (to the best
of my knowledge).


Regards,

    Gabriel

Re: [Jsdoc-user] Hiding constructor details

[Gabriel R. <gab...@gm...>]

On Mon, Mar 26, 2007 at 03:37:31PM +0100, Bruce Boughton wrote:
> Gabriel Reid wrote:
> >Could you provide a bit more explanation, or another example (pointing
> >out the information that you want to be hidden, and where you're putting
> >the @ignore or @private tag)?
> >  
> My previous example may not have worked as I modified it a bit to 
> anonymise it. 
> 
> I have modified my code slightly, which I show below. This correctly 
> hides the constructor, but it has the side-effect of hiding the class 
> description. I appreciate JavaScript does not make it easy for JSDoc by 
> combining the class declaration and constructor into one object!
> 
> My constructs may look a little strange. I declare privileged functions 
> inside the _wbinit method (called by the ctor) which have access to 
> private member variables. If I attach JSDoc documentation directly to 
> these JSDoc does not see it (because they are inside the _wbinit 
> method), so I am aliasing them from methods declared after _wbinit, 
> which are documented.
> 

I've looked at this problem a bit, and as it stands, I'd say that it's
not really possible to achieve exactly what you want to do with JSDoc
(hiding constructor details while showing class information).

You could play around a bit more with things as you've done to try to
trick JSDoc into providing what you want, but that also goes against the
whole idea of JSDoc (it's supposed to reduce your work, not increase it).


- Gabriel

Re: [Jsdoc-user] custom tags and creating a default view

[Gabriel R. <gab...@gm...>]

Hi Kate,

> 1)       What are the steps for creating a custom JSDoc tag? I want an
> @Example tag where I can provide 2 or 3 lines of code to show how an
> object/function/etc can be implemented. I may be able to figure out
> which tmpl (or other) file I should go into to create the tag, but I'm a
> little pressed for time on my project, so I first thought I'd see if
> anyone already has some steps for how to create a tag.

The support for custom tags in JSDoc is based on being able to write a
very small bit of Perl code. You can define custom tags in the
.jsdoc_config file. For the example you're describing, a start would be
to add something like this to .jsdoc_config

   $METHOD_ATTRS_MAP{example} =
        sub {
            my $ex = $_[0][0];
            return "<div style='background: #CCCCCC; border: dashed 2px; padding: 12px; width: 70%'> <code>$ex</code></div>";
        };

This would put all text given as an @example in a shaded and bordered
block in the HTML. 

One of the downsides of this approach is that you can't control where
the block will be displayed; it will simply be together with the other
tag output (like @return and @param). 

Also, newlines and whitespace formatting are stripped from tag input
like this, which is probably not really what you want...


> 
> 2)       Is there a way to set how JSDoc opens when people click the
> index.html file? Ideally I would like them have the index.html file open
> with the "Overview" material provided at the top. As it is now, if you
> click index.html, you then have to click the link at the top called
> "Overview" to get the look that I would like to present people upon
> first opening the file. Is there a way to do this? 

The behaviour of JSDoc is:
    - If there is an overview page supplied, and more than one
      JavaScript file is being processed, the opening page will be the
      Overview page.

    - Otherwise, the first class page is displayed.


Hope this is of some help.


Regards,

    Gabriel

Re: [Jsdoc-user] public properties?

[Gabriel R. <gab...@gm...>]

On Wed, Mar 28, 2007 at 10:48:45AM -0700, Jake Devine wrote:
> Hi Anthony,
> 
> Documenting a public property is the same as with a method.  I'm not exactly
> sure of your syntax, but likely this would work:
> 
> ---snip---
> /**
> * A sample public property
> * @type Number
> */
> some_public_property: 2,
> /**
> * A sample function
> * @param p something
> */
> a_func = function(p) {
> ---snip---

Yes indeed, in this kind of block properties are recognized in the same
way as functions. However, JSDoc only recognizes these kinds of blocks
in an assignment of an object definition to a function prototype, as follows:

Foo.prototype = {
    /**
     * Just an example.
     */
    some_public_property: 2,

    /**
     * Here's an example method.
     * @param p
     */
    a_func: function(p) {
        return null;
    }
};


- Gabriel

Re: [Jsdoc-user] public properties?

[Jake D. <jak...@ni...>]

Hi Anthony,

Documenting a public property is the same as with a method.  I'm not exactly
sure of your syntax, but likely this would work:

---snip---
/**
 * A sample public property
 * @type Number
 */
some_public_property: 2,
/**
 * A sample function
 * @param p something
 */
a_func = function(p) {
---snip---

jake

On 3/27/07, Anthony Ettinger <an...@ch...> wrote:
>
> Is it bad form to have a public property?
> I'm not seeing any way to note this in JSDoc.
>
> ie:
>
> Foo.bar: {
>      some_public_property: 2,
>      a_func: function(p) {
>
>     }
> }
>
>
> Such that I can set it with:
>
> Foo.bar.some_public_property = 3;
>
> Seems we need a JSDoc "@public" notation.
>
>
>
> --
> Anthony Ettinger
> Ph: 408-656-2473
> http://chovy.dyndns.org/resume.html
> http://utuxia.com/consulting
>
> -------------------------------------------------------------------------
> Take Surveys. Earn Cash. Influence the Future of IT
> Join SourceForge.net's Techsay panel and you'll get the chance to share
> your
> opinions on IT & business topics through brief surveys-and earn cash
> http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV
> _______________________________________________
> Jsdoc-user mailing list
> Jsd...@li...
> https://lists.sourceforge.net/lists/listinfo/jsdoc-user
>

Re: [Jsdoc-user] public properties?

[Michael M. <mi...@gm...>]

Hi Anthony,

You're looking on the wrong tagref page. Erm, OK, so JSDoc-2 doesn't  
yet have a "tagref" page...

The property tag is mentioned on the new JSDoc-2 wiki, here...
     http://code.google.com/p/jsdoc-2/wiki/JsdocCookbook
and here...
     http://code.google.com/p/jsdoc-2/wiki/JsLang

The point is: JSDoc-2 is a complete rewrite of JSDoc 1.x, its still  
in beta, and has it's own project page. If you're willing to give us  
a hand you can try JSDoc-2 out and share your feedback. We expect to  
release a final 1.0 version of JSDoc-2 in July.

I've gone ahead and posted a working example for you here...
    http://jsdoc.info/export/examples/fly/html/picky.html
    (choose the "anthony.js" library, with the "sunny" template)

If you're not into beta you can stick with JSDoc 1.x -- it's not  
going away any time soon. I'm sure Gabriel, or one of the other JSDoc  
1.x users will be able to help.

Regards,
Michael



On 28 Mar 2007, at 00:33, Anthony Ettinger wrote:

> On 3/27/07, Michael Mathews <mi...@gm...> wrote:
>> Hi Anthony,
>>
>> I'm afraid I don't understand your example. Perhaps you trimmed too
>> much, because the Foo.bar code you gave isn't valid JS. Did you mean:
>>
>> Foo = {
>>    bar: {
>>      some_public_property: 2,
>>      a_func: function(p) {
>>      }
>>    }
>> };
>>
>> Foo.bar.some_public_property = 3;
>>
>> I can't be certain of JSDoc 1.x (perhaps Gabriel will follow up) but
>> in JSDoc-2 one way to document the above would be like so:
>>
>> /**
>> * Container object.
>> * @namespace
>> */
>> Foo = {
>>    /**
>>     * Just an example.
>>     * @namespace
>>     * @property {number} some_public_property
>>     */
>>    bar: {
>>      some_public_property: 2,
>>      /**
>>       * Here's an example method.
>>       * @method
>>       * @param p
>>       */
>>      a_func: function(p) {
>>      }
>>    }
>> };
>>
>> This would add all your objects to the output. I can post an example
>> of this on the web if you like and you can try it yourself.
>>
>> Regards,
>> Michael
>>
>> On 27 Mar 2007, at 22:58, Anthony Ettinger wrote:
>>
>> > Is it bad form to have a public property?
>> > I'm not seeing any way to note this in JSDoc.
>> >
>> > ie:
>> >
>> > Foo.bar: {
>> >      some_public_property: 2,
>> >      a_func: function(p) {
>> >
>> >     }
>> > }
>> >
>> >
>> > Such that I can set it with:
>> >
>> > Foo.bar.some_public_property = 3;
>> >
>> > Seems we need a JSDoc "@public" notation.
>
>
> I don't see @property anywhere in the #tagref page.
>
>
>
> -- 
> Anthony Ettinger
> Ph: 408-656-2473
> http://chovy.dyndns.org/resume.html
> http://utuxia.com/consulting

Re: [Jsdoc-user] public properties?

[Anthony E. <an...@ch...>]

On 3/27/07, Michael Mathews <mi...@gm...> wrote:
> Hi Anthony,
>
> I'm afraid I don't understand your example. Perhaps you trimmed too
> much, because the Foo.bar code you gave isn't valid JS. Did you mean:
>
> Foo = {
>    bar: {
>      some_public_property: 2,
>      a_func: function(p) {
>      }
>    }
> };
>
> Foo.bar.some_public_property = 3;
>
> I can't be certain of JSDoc 1.x (perhaps Gabriel will follow up) but
> in JSDoc-2 one way to document the above would be like so:
>
> /**
> * Container object.
> * @namespace
> */
> Foo = {
>    /**
>     * Just an example.
>     * @namespace
>     * @property {number} some_public_property
>     */
>    bar: {
>      some_public_property: 2,
>      /**
>       * Here's an example method.
>       * @method
>       * @param p
>       */
>      a_func: function(p) {
>      }
>    }
> };
>
> This would add all your objects to the output. I can post an example
> of this on the web if you like and you can try it yourself.
>
> Regards,
> Michael
>
> On 27 Mar 2007, at 22:58, Anthony Ettinger wrote:
>
> > Is it bad form to have a public property?
> > I'm not seeing any way to note this in JSDoc.
> >
> > ie:
> >
> > Foo.bar: {
> >      some_public_property: 2,
> >      a_func: function(p) {
> >
> >     }
> > }
> >
> >
> > Such that I can set it with:
> >
> > Foo.bar.some_public_property = 3;
> >
> > Seems we need a JSDoc "@public" notation.


I don't see @property anywhere in the #tagref page.



-- 
Anthony Ettinger
Ph: 408-656-2473
http://chovy.dyndns.org/resume.html
http://utuxia.com/consulting

Re: [Jsdoc-user] public properties?

[Michael M. <mi...@gm...>]

Hi Anthony,

I'm afraid I don't understand your example. Perhaps you trimmed too  
much, because the Foo.bar code you gave isn't valid JS. Did you mean:

Foo = {
   bar: {
     some_public_property: 2,
     a_func: function(p) {
     }
   }
};

Foo.bar.some_public_property = 3;

I can't be certain of JSDoc 1.x (perhaps Gabriel will follow up) but  
in JSDoc-2 one way to document the above would be like so:

/**
* Container object.
* @namespace
*/
Foo = {
   /**
    * Just an example.
    * @namespace
    * @property {number} some_public_property
    */
   bar: {
     some_public_property: 2,
     /**
      * Here's an example method.
      * @method
      * @param p
      */
     a_func: function(p) {
     }
   }
};

This would add all your objects to the output. I can post an example  
of this on the web if you like and you can try it yourself.

Regards,
Michael

On 27 Mar 2007, at 22:58, Anthony Ettinger wrote:

> Is it bad form to have a public property?
> I'm not seeing any way to note this in JSDoc.
>
> ie:
>
> Foo.bar: {
>      some_public_property: 2,
>      a_func: function(p) {
>
>     }
> }
>
>
> Such that I can set it with:
>
> Foo.bar.some_public_property = 3;
>
> Seems we need a JSDoc "@public" notation.
>
>
>
> -- 
> Anthony Ettinger
> Ph: 408-656-2473
> http://chovy.dyndns.org/resume.html
> http://utuxia.com/consulting
>
> ---------------------------------------------------------------------- 
> ---
> Take Surveys. Earn Cash. Influence the Future of IT
> Join SourceForge.net's Techsay panel and you'll get the chance to  
> share your
> opinions on IT & business topics through brief surveys-and earn cash
> http://www.techsay.com/default.php? 
> page=join.php&p=sourceforge&CID=DEVDEV
> _______________________________________________
> Jsdoc-user mailing list
> Jsd...@li...
> https://lists.sourceforge.net/lists/listinfo/jsdoc-user

[Jsdoc-user] custom tags and creating a default view

[Rodrigues, K. <kro...@ne...>]

Hi there -=20

I've got two questions for the group.

=20

1)       What are the steps for creating a custom JSDoc tag? I want an
@Example tag where I can provide 2 or 3 lines of code to show how an
object/function/etc can be implemented. I may be able to figure out
which tmpl (or other) file I should go into to create the tag, but I'm a
little pressed for time on my project, so I first thought I'd see if
anyone already has some steps for how to create a tag.

2)       Is there a way to set how JSDoc opens when people click the
index.html file? Ideally I would like them have the index.html file open
with the "Overview" material provided at the top. As it is now, if you
click index.html, you then have to click the link at the top called
"Overview" to get the look that I would like to present people upon
first opening the file. Is there a way to do this?=20

=20

Thanks!

kate=20

[Jsdoc-user] public properties?

[Anthony E. <an...@ch...>]

Is it bad form to have a public property?
I'm not seeing any way to note this in JSDoc.

ie:

Foo.bar: {
     some_public_property: 2,
     a_func: function(p) {

    }
}


Such that I can set it with:

Foo.bar.some_public_property = 3;

Seems we need a JSDoc "@public" notation.



-- 
Anthony Ettinger
Ph: 408-656-2473
http://chovy.dyndns.org/resume.html
http://utuxia.com/consulting

Re: [Jsdoc-user] comment syntax

[Gabriel R. <gab...@gm...>]

>
> So the /** two stars trigger JSDoc documentation?
>

That's correct. The star at the beginning of lines in between the
opening and closing of the block aren't necessary, they're usually
just put there (either manually or automatically) for aesthetic
reasons.

Gabriel

Re: [Jsdoc-user] comment syntax

[Anthony E. <an...@ch...>]

On 3/26/07, Jake Devine <jak...@ni...> wrote:
> Only
>
> /**
> My function
> @param myparam
> */
>
> is necessary Anthony (notice the two stars /** at the start).  Most
> javascript editors will add the stars and indent each line in between,
> that's probably why you've seen documentation that looks that way.
>
> Jake


So the /** two stars trigger JSDoc documentation?


-- 
Anthony Ettinger
Ph: 408-656-2473
http://chovy.dyndns.org/resume.html
http://utuxia.com/consulting

Re: [Jsdoc-user] comment syntax

[Jake D. <jak...@ni...>]

Only

/**
My function
@param myparam
*/

is necessary Anthony (notice the two stars /** at the start).  Most
javascript editors will add the stars and indent each line in between,
that's probably why you've seen documentation that looks that way.

Jake

On 3/26/07, Anthony Ettinger <an...@ch...> wrote:
>
> is this really necessary for JSDoc to work?
>
> /**
> *
> *
> *
> *
> *
> */
>
> or is that just format style.
>
> I'd rather just do:
>
> /*
> My description here...
>
> @method Foo();
> @param Bar {String} Refers to the 'bar' object
>
> */
>
>
> Sorry I couldn't just "try it" because I'm not actually using JSDoc yet.
>
>
>
> --
> Anthony Ettinger
> Ph: 408-656-2473
> http://chovy.dyndns.org/resume.html
> http://utuxia.com/consulting
>
> -------------------------------------------------------------------------
> Take Surveys. Earn Cash. Influence the Future of IT
> Join SourceForge.net's Techsay panel and you'll get the chance to share
> your
> opinions on IT & business topics through brief surveys-and earn cash
> http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV
> _______________________________________________
> Jsdoc-user mailing list
> Jsd...@li...
> https://lists.sourceforge.net/lists/listinfo/jsdoc-user
>

[Jsdoc-user] comment syntax

[Anthony E. <an...@ch...>]

is this really necessary for JSDoc to work?

/**
*
*
*
*
*
*/

or is that just format style.

I'd rather just do:

/*
 My description here...

@method Foo();
@param Bar {String} Refers to the 'bar' object

*/


Sorry I couldn't just "try it" because I'm not actually using JSDoc yet.



-- 
Anthony Ettinger
Ph: 408-656-2473
http://chovy.dyndns.org/resume.html
http://utuxia.com/consulting

[Jsdoc-user] Prototypical inheritence of built-in types creates entries for built-in types in class list

[Bruce B. <br...@br...>]

Hi,

I'm having a problem with JSDoc where, when I declare a class which 
prototypically inherits from a built-in such as Error, JSDoc creates an 
entry for Error in the class list which does not link to anywhere (since 
I do not define the Error class in my code).  Is it possible to give 
JSDoc a list of types not to include in the class list or link to?  I 
have found the same to occur when prototypically 'extending' String and 
Object too.  I include a code snippet below.

I tried to look through the JSDoc.pl file to see where would be an 
appropriate place to put some code to ignore built-ins but didn't have 
much luck understanding where the class list and links are generated.

Bruce

/**
* @class The WBSI global namespace object.
* @static
*/
var WBSI = function() { };

/**
 * Create a IllegalArgumentException with an associated explanation, 
operation
 * and arguument list.
 *
 * @class An IllegalArgumentException will be thrown if an operation is
 * invoked with incorrect or invalid parameters
 *
 * @param {String} explanation            Explanation of exception
 *
 * @param {Object} func                    The operation invoked
 *
 * @param {Object[]} args                The arguments the operation was
 *                                         invoked with
 */
WBSI.IllegalArgumentException = function(explanation, func, args)
{   
    this._wbinit(explanation, func, args);
}

/**
 * @extends Error
 */
WBSI.IllegalArgumentException.prototype=new Error;

/**
 * The explanation for why the exception was thrown
 *
 * @property explanation
 * @type String
 */
WBSI.IllegalArgumentException.prototype.explanation = null;

/**
 * The operation invoked
 *
 * @property operation
 * @type Object
 */
WBSI.IllegalArgumentException.prototype.operation = null;

/**
 * The arguments the operation was invoked with
 *
 * @property arglist
 * @type Object[]
 */
WBSI.IllegalArgumentException.prototype.arglist = null;

/**
 * @method    _wbinit
 * @ignore
 */
WBSI.IllegalArgumentException.prototype._wbinit = function(ex, op, args) {
    this.explanation = ex;
    this.operation = op;
    this.arglist = args;
};