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

Re: [Jsdoc-user] no jsdoc from valid javscript

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

On Sun, Jul 30, 2006 at 09:10:28PM +0200, Henrik Gemal wrote:
> Gabriel Reid wrote:
> >On Thu, Jul 27, 2006 at 08:29:58AM +0200, Henrik Gemal wrote:
> >  
> >>If I have valid JavaScript like this:
> >>
> >>var DED = function() {
> >>	var private_var;
> >>	function private_method() {}
> >>	return {
> >>		public_var: 1,
> >>		public_method : function() {}
> >>	};
> >>}();
> >>
> >>I dont get any jsdocs out:
> >>Loading sources from test.js
> >>Nothing to document, exiting
> >>What can I do?
> >>
> >>    
> >
> >If you change the first line of this to:
> >    
> >    var DED = new function(){
> >
> >then you should get results much closer to what you're expecting,
> >without changing the functionality of your JavaScript code. The "new"
> >keyword here is unfortunately an extra hint that the current incarnation
> >of JSDoc needs in order to document this code.
> >  
> It's correct that if I use "new function", I no longer get no jsdocs. 
> But if you try to generate JSDoc from:
> 
> var bla = new function() {
>        var priv = 1;
>        return {
>                tester : function() {},
>        }
> }();
> 
> The "tester" function isn't mentioned. Isn't this a bug?

Yes, this could indeed be considered a bug. Unfortunately, it's not a
bug that is likely to be fixed in the near future (at least not in the
current incarnation of JSDoc). The current version lacks a real
JavaScript parser, making it very difficult to handle constructs such as
this one. 

Regards,

    Gabriel

Re: [Jsdoc-user] no jsdoc from valid javscript

[Henrik G. <sp...@ma...>]

Gabriel Reid wrote:
> On Thu, Jul 27, 2006 at 08:29:58AM +0200, Henrik Gemal wrote:
>   
>> If I have valid JavaScript like this:
>>
>> var DED = function() {
>> 	var private_var;
>> 	function private_method() {}
>> 	return {
>> 		public_var: 1,
>> 		public_method : function() {}
>> 	};
>> }();
>>
>> I dont get any jsdocs out:
>> Loading sources from test.js
>> Nothing to document, exiting
>> What can I do?
>>
>>     
>
> If you change the first line of this to:
>     
>     var DED = new function(){
>
> then you should get results much closer to what you're expecting,
> without changing the functionality of your JavaScript code. The "new"
> keyword here is unfortunately an extra hint that the current incarnation
> of JSDoc needs in order to document this code.
>   
It's correct that if I use "new function", I no longer get no jsdocs. 
But if you try to generate JSDoc from:

var bla = new function() {
        var priv = 1;
        return {
                tester : function() {},
        }
}();

The "tester" function isn't mentioned. Isn't this a bug?

Re: [Jsdoc-user] no jsdoc from valid javscript

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

On Thu, Jul 27, 2006 at 08:29:58AM +0200, Henrik Gemal wrote:
> If I have valid JavaScript like this:
> 
> var DED = function() {
> 	var private_var;
> 	function private_method() {}
> 	return {
> 		public_var: 1,
> 		public_method : function() {}
> 	};
> }();
> 
> I dont get any jsdocs out:
> Loading sources from test.js
> Nothing to document, exiting
> What can I do?
> 

If you change the first line of this to:
    
    var DED = new function(){

then you should get results much closer to what you're expecting,
without changing the functionality of your JavaScript code. The "new"
keyword here is unfortunately an extra hint that the current incarnation
of JSDoc needs in order to document this code.

Regards,

Gabriel

Re: [Jsdoc-user] no jsdoc from valid javscript

[Larry R. <lj...@ho...>]

I have had a similar issue. Im not sure if it's a bug in JSDoc or what, but
try this:

var DED;

/**
 * comments....
 */
DED = function () {
	Blah....
}

For me I found I had to remove the var declaration from the line. Hope it
works for you too.


-----Original Message-----
From: jsd...@li...
[mailto:jsd...@li...] On Behalf Of Henrik Gemal
Sent: Wednesday, July 26, 2006 11:30 PM
To: jsd...@li...
Subject: [Jsdoc-user] no jsdoc from valid javscript

If I have valid JavaScript like this:

var DED = function() {
	var private_var;
	function private_method() {}
	return {
		public_var: 1,
		public_method : function() {}
	};
}();

I dont get any jsdocs out:
Loading sources from test.js
Nothing to document, exiting
What can I do?

Using JSDoc-1.9.9.2

-------------------------------------------------------------------------
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] no jsdoc from valid javscript

[<he...@ma...>]

|If I have valid JavaScript like this:

var DED = function() {
	/var private_var;/
	/function private_method()/ {
		// do stuff here
	}
	return {
		method_1 : function() {
			// do stuff here
		}
	};
}();

I dont get any jsdocs out:
Loading sources from test.js
Nothing to document, exiting

What can I do?

|

[Jsdoc-user] no jsdoc from valid javscript

[Henrik G. <he...@ma...>]

If I have valid JavaScript like this:

var DED = function() {
	var private_var;
	function private_method() {}
	return {
		public_var: 1,
		public_method : function() {}
	};
}();

I dont get any jsdocs out:
Loading sources from test.js
Nothing to document, exiting
What can I do?

Using JSDoc-1.9.9.2

[Jsdoc-user] escaping special characters

[Matthew G. <mat...@gm...>]

hi.

i'm using jsdoc for documentation and i've placed some sample xml code =
in my comments and they're not being output. how do i escape them? =
here's an example line of code that isn't showing up in the =
documentation.=20

thank you in advance for any helpful tips. -- matt.=20

<abc:location id=3D"1" osid=3D"12345" rowid=3D"1" =
x=3D"-96.8227984457377" y=3D"32.8196376234957" />

Re: [Jsdoc-user] Handling multiple files

[Ian P. <isp...@gm...>]

jsdoc.pl has been happy to document an entire directory for me for
quite some time.  Just give it all the filenames and you're good to
go.  JSDoc is truly brilliant.

Ian, happy JSDoc user

On 3/8/06, Jim Foster <jf...@tm...> wrote:
> Hello!
>
> I have been looking for a JavaScript documentation tool (that understood
> JavaScript's strange way dealing with inheritance) for some time.
>
> I finally found this tool, and my first impressions are very positive.
>
> A simple question, if I may.
>
> What if one has a library of JavaScript files in a directory?
>
> I mean by this a group of related files that inherit and extend, and all
> make up what one would conventionally call a "package".
>
>  From what I can see at http://jsdoc.sourceforge.net/, there is just the
> one-file command line. I do not see any reference to a command line with
> something like
>
>   perl jsdoc.pl *.js
>
>
> I looked at the Perl code, but my Perl skills haven't been used in
> years, and are hardly reliable, anymore.
>
> If this is already documented, and I simply overlooked it, my apologies,
> and could you please direct me?
>
>
> Jim
>
>
> -------------------------------------------------------
> This SF.Net email is sponsored by xPML, a groundbreaking scripting langua=
ge
> that extends applications into web and mobile media. Attend the live webc=
ast
> and join the prime developer group breaking into this new coding territor=
y!
> http://sel.as-us.falkag.net/sel?cmd=3Dlnk&kid=3D110944&bid=3D241720&dat=
=3D121642
> _______________________________________________
> Jsdoc-user mailing list
> Jsd...@li...
> https://lists.sourceforge.net/lists/listinfo/jsdoc-user
>


--
Tired of pop-ups, security holes, and spyware?
Try Firefox: http://www.getfirefox.com

[Jsdoc-user] Handling multiple files

[Jim F. <jf...@tm...>]

Hello!

I have been looking for a JavaScript documentation tool (that understood 
JavaScript's strange way dealing with inheritance) for some time.

I finally found this tool, and my first impressions are very positive.

A simple question, if I may.

What if one has a library of JavaScript files in a directory?

I mean by this a group of related files that inherit and extend, and all 
make up what one would conventionally call a "package".

 From what I can see at http://jsdoc.sourceforge.net/, there is just the 
one-file command line. I do not see any reference to a command line with 
something like

  perl jsdoc.pl *.js


I looked at the Perl code, but my Perl skills haven't been used in 
years, and are hardly reliable, anymore.

If this is already documented, and I simply overlooked it, my apologies, 
and could you please direct me?


Jim

[Jsdoc-user] Bruce Wallace is out of town.

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

I will be out of the office starting  03/02/2006 and will not return until
03/07/2006.

I will respond to your message when I return.

Re: [Jsdoc-user] Argument list turns up empty-()- if constructor is assigned to static functions

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

On Mon, Mar 06, 2006 at 04:22:16AM -0500, Raymond A. Orr wrote:
> Hello:
> 
> In order to prevent collisions with other JavaScript libraries I like to
> prefix all public classes and functions with two static functions like
> (org.ui).  When I do that, the (a,b) constructor arguments as in the example
> below do not show up under Constructor Summary or Detail. Other than that,
> everything about the class shows up perfectly in JSDoc. This example
> duplicates this behavior.
> 

This is resolved in version 1.9.9.2 of JSDoc; thanks for reporting it.

Regards,

    Gabriel

[Jsdoc-user] Argument list turns up empty-()- if constructor is assigned to static functions

[Raymond A. O. <ra...@op...>]

Hello:

In order to prevent collisions with other JavaScript libraries I like to
prefix all public classes and functions with two static functions like
(org.ui).  When I do that, the (a,b) constructor arguments as in the example
below do not show up under Constructor Summary or Detail. Other than that,
everything about the class shows up perfectly in JSDoc. This example
duplicates this behavior.

//start example
function org(){}
function ui(){}

org.ui=ui;

/**
* Arguments do not show up in Constructor Summary.
* @param a Describe a.
* @param b Describe b.
* @constructor
*/
org.ui.CreateDrop=function(a,b){}

/**
* Arguments do show up in Constructor Summary.
* @param a Describe a.
* @param b Describe b.
* @constructor
*/
function ShowDrop(a,b){}
//end example

Here is a snapshot of xml output:
-----------
        <class 
            name="org.ui.CreateDrop" 
                 >
            <constructor_args>()</constructor_args>
-----------
        <class 
            name="ShowDrop" 
                 >
            <constructor_args>(a,b)</constructor_args>

Any ideas on a workaround or fix?  JSDoc is so close on this one.

Gabriel and Michael, thanks for creating this product.

Ray

Re: [Jsdoc-user] Template directory parameter

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

On Mon, Feb 13, 2006 at 04:28:02PM +1300, Adam Ratcliffe wrote:
> Hi,
> 
> I've customized the JSDoc templates and stylesheet to produce a look  
> that's consistent with our other documentation that links through to  
> the API docs.  It would be really great if I could specify an  
> external directory containing these templates as a command line  
> argument to jsdoc.pl as this would eliminate the need to copy these  
> templates into the jsdoc install directory each time I do an upgrade.
> 
> WDYT?

Sounds like a good idea to me, and it's something that's been asked for
before. It'll be in the next release.

- Gabriel

[Jsdoc-user] Template directory parameter

[Adam R. <ad...@pr...>]

Hi,

I've customized the JSDoc templates and stylesheet to produce a look  
that's consistent with our other documentation that links through to  
the API docs.  It would be really great if I could specify an  
external directory containing these templates as a command line  
argument to jsdoc.pl as this would eliminate the need to copy these  
templates into the jsdoc install directory each time I do an upgrade.

WDYT?

Cheers
Adam

Re: [Jsdoc-user] How to specify description for Constructor Summary/Detail

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

 
> Is there a way to specify the description for the class constructor  
> summary and/or detail?
> 

The starting documentation in the documentation block for a constructor
function will be used as the summary/detail for that constructor. For
example:

/**
 * This is the class constructor summary. This second sentence will only
 * appear in the constructor detail.
 * @class This is the optional class information.
 */
function MyClassConstructor(){
}


Hope this is what you were looking for.

- Gabriel

[Jsdoc-user] How to specify description for Constructor Summary/Detail

[Adam R. <ad...@pr...>]

Hi Gabriel

Is there a way to specify the description for the class constructor  
summary and/or detail?

Cheers
Adam

Re: [Jsdoc-user] generated HTML missing method details unless class used

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

On Fri, Jan 06, 2006 at 01:33:02PM -0500, bru...@wa... wrote:
> thanks.
> BTW(1), when trying to test your suggestion, I tried the little file 
> attached
> and JsDoc failed and said...
> Loading sources from observer3.js
> Can't use an undefined value as an ARRAY reference at 
> c:\JSDoc-1.9.8\jsdoc.pl line 1096.

This has been fixed in JSDoc 1.9.8.1. Thanks for pointing it out.

> BTW(2), here is an enhancement request....
> Allow filenames in the @requires tag (at least in the comment block with 
> @fileoverview)
> so that one .js file can note its dependence on other .js files.
> While JsDoc will place the referenced file in the HTML in plain text,
> it gives error messages when running JsDoc. Also, it would be nice for
> the filename to actually be a link in the HTML to the referenced .js file
> thanks, Bruce Wallace

Could you register this as an RFE on sourceforge.net? By the way, you
can alter the handling of '@' tags in the .jsdoc_config file. When this
does get implemented, it will probably be introduced as an entry in that
file, as this is quite a customized request. If you'd like a hand with
adding this to your .jsdoc_config file, just let me know.

Gabriel

Re: [Jsdoc-user] generated HTML missing method details unless class used

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

On Fri, Jan 06, 2006 at 11:32:25AM -0500, bru...@wa... wrote:
> here is a copy of a posting to the bug list...[Im not sure how often that 
> is monitored
> since all the other bugs in the list haven't been assigned and some are 
> over a
> year old]...

Actually, the bugs list is indeed monitored quite regularly. The bugs
that are still up there are generally (currently) not really solvable.
They don't get assigned because there's only me to assign them to myself :)

> When the attached file is processed with 1.9.8 it
> produces HTML missing the documention for each of the
> methods of the single class in this file (Map).
> 
> However, if the very last line [which simply does a
> "new Map()" ] is uncommented, then the proper HTML is
> produced.
> 
> The code should not have to actually use a class in
> order for that class to be documented!
> 
> I have verified that there can be arbitrary amounts of
> code added to the file, and as long as Map is
> instantiated somewhere in that code, Map methods are
> properly documented in the HTML but not otherwise.

JSDoc doesn't recognize Map as being a constructor without the call to
it. This can also be accomplished by adding a @constructor tag to Map's
documentation block. The next release of JSDoc won't require a
@constructor tag if the @class tag is used for the same function (which
is the case in your file). 

Gabriel

[Jsdoc-user] generated HTML missing method details unless class used

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

here is a copy of a posting to the bug list...[Im not sure how often that 
is monitored
since all the other bugs in the list haven't been assigned and some are 
over a
year old]...


When the attached file is processed with 1.9.8 it
produces HTML missing the documention for each of the
methods of the single class in this file (Map).

However, if the very last line [which simply does a
"new Map()" ] is uncommented, then the proper HTML is
produced.

The code should not have to actually use a class in
order for that class to be documented!

I have verified that there can be arbitrary amounts of
code added to the file, and as long as Map is
instantiated somewhere in that code, Map methods are
properly documented in the HTML but not otherwise.

Re: [Jsdoc-user] Object/Class declaration in separate file/function

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

On Thu, Jan 05, 2006 at 03:40:33PM -0500, mb...@we... wrote:
> Thanks for the advice.  It kinda worked, but here's what I found:
> 
> My functions are defined as such:
> 
>    /**
>     * @member myClass
>     */
>    A.B.C.myFunction = function()
>    {
>    }
> 
> JSDoc doesn't seem to pick this up unless i first put a normal function
> such as
> 
>    /**
>     * @member myClass
>     */
>    function tmpFunction()
>    {
>    }
> 
> If that comes first, it picks up all the others without even having to put
> @member ... in their doc blocks.  If the dummy function comes after the
> others, the only thing it picks up is the dummy function.
> 
> Is that a bug?  Or do i just need to include a dummy function in all of my
> files?


I'm just realizing now (or I think I'm just realizing) that we're
actually talking about functions being added to an instance, not a
class. In that case, this isn't really the idea behind JSDoc, but I'm
not totally sure that I'm fully comprehending the whole problem.

I wouldn't really call it a bug, as the @member tag is intended for
linking normally defined functions to a class, so this is actually a bit
of misuse of that construct.

In any case, from what I've seen of what you're doing, there's no need
to define a dummy function; instead, you can just define one of the
functions as a named function with the @member tag, and then bind that
named function to the instance/class that you want to bind it to.

If this isn't really solving the issue here (and I have a feeling that
it isn't), could you post a more complete example, along with what you
would like/expect to see as the output of JSDoc?

Regards,
    Gabriel

[Jsdoc-user] Object/Class declaration in separate file/function

[<mb...@we...>]

I'm trying to use a function to dynamically create objects from a string
instead of creating all objects and subobjects manually.  Example:

myFunction("A.B.C");

performs the following:
  A =3D new function() {};
  A.B =3D new function() {};
  A.B.C =3D new function() {};

This function is in a separate file, but I don't think that matters.

In my actual JS files I simply call myFunction and proceed to define
functions on that object.  But since in that file the object isn't
explicitly declared, JSDoc doesn't seem to be picking it up.

Is there any way to tweak JSDoc or use a tag as a workaround to get it to
recognize the object?

Thanks,
Mike

---
mb...@we...
http://mikebulman.typepad.com

Webmail.us, Inc.
"The Email Hosting Company"

Re: [Jsdoc-user] Use javascript code in comments

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

Hi,

> Is it possible to use Javascript code in jsdoc comments?
>=20
> The following example doesn't output html as I
> would expect. JSDOC cut all the code in {}.
>=20
> /**
>  * Fun=E7=E3o para cria=E7=E3o de classe. O m=E9todo de nome
>  * "init" ser=E1 usado como construtor da classe.
>  * <p>
>  * Exemplo da cria=E7=E3o de uma classe:
>  * <pre>
>  * c1 =3D function() {this.__init__(arguments);}
>  * c1.Class();
>  * c1.prototype.init =3D function( msg ) {
>  *   this.msg =3D msg;
>  * }
>  * var obj =3D new c1( "Teste Objeto" );
>  * </pre>
>  *
>  * @return Function
>  */

Could you send me a small example JavaScript source file that I can use
to replicate this problem? I'm having trouble replicating it with=20
JSDoc 1.9.7.

Thanks,
    Gabriel

Re: [Jsdoc-user] JSDoc 1.9.7 Constants

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

On Wed, Dec 21, 2005 at 06:09:27PM +0000, Max d'Ayala wrote:
> Hello Gabriel.
> 
> Looking at the latest 1.9.7 version I noticed the following minor error 
> with stylesheet.css:
> ...
> the font-size should be "pt" rather than "pts".

Just fixed it in my CVS repository, and it'll be in the next release.
Thanks for pointing that out!

> 
> Looking at Constant value I have a couple of questions.
> 
> 1. It would be nice if there was a link in the bottom left window 
> showing "All Classes" to the "Constant Field Values" page.
> At the moment the only way I can find of getting there is to find a 
> constant value and then click on the link to the page.
> 
> 
> 2. When prototype properties are flagged as "@final" they don't show up 
> on the Constant Field Values page.
> 
> Here is an example.
> 
> function MyObject() {
>  // Constructor function.
> }
> 
> /**
> Constant prototype number, value = 10.
> This doesn't get documented on the Constants page,
> although the Field Details do have a link to the Constant Field Values 
> page.
> 
> @final
> */
> MyObject.prototype.constant_prototype_number = 10;
> 
> /**
> Constant number, value = 20.
> This gets documented in the Constant Field Values page.
> 
> @final
> */
> MyObject.constant_number = 20;
> 

Both of these points are the result of JSDoc trying to follow the
example of javadoc. However, they both seem reasonable, so if nobody has
any objections to them, it shouldn't be a problem to add them. Could you
please add them to the request tracker on sourceforge? That way I can be
sure I won't forget about it. You may notice that there are already
quite a few requests waiting to be dealt with there, but I'm hoping to
make some decent progress over Christmas.

Regards,
    Gabriel

Re: [Jsdoc-user] How to reference classes in other files

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

On Tue, Dec 20, 2005 at 05:10:08PM -0800, Sergio Pinon wrote:
> Please forgive me if this has already been answered before. I am new to this group. I was trying to figure out how to show that the subclassed object is in another file and when the user clicks that object it clicks to the other file. So here is how my files look
> 
> 
> File A:
> 
> function _Class1()
> 
> {
> 
>             this.Class2= _ Class2();
> 
> }
> 
>  
> 
>  
> 
> File B:
> 
> function _ Class2()
> 
> {
> 
> this.Class2Method = function ()
> 
> {
> 
>             //statement here
> 
> }
> 
> }
> 
>  
> 
> Class1. Class2.FileBMethod()
> 
>  
> 
> How can I show this relationship with JSDOC. I can't seem to figure this out.
> 

I'm not clear on the relationship that you're trying to show with JSDoc.
What do you mean with "it clicks to the other file"?

In any case, I think you'll get better results by adding a JSDoc comment
block with the @constructor tag in it above each of the constructor
functions in the above code (_Class1 and _Class2).

If that doesn't get you what you need, could you try explaining more
about the relationship that you want JSDoc to show?


Regards,
    Gabriel

[Jsdoc-user] Use javascript code in comments

[Marco C. <mar...@gm...>]

Hello,

Is it possible to use Javascript code in jsdoc comments?

The following example doesn't output html as I
would expect. JSDOC cut all the code in {}.

/**
 * Fun=E7=E3o para cria=E7=E3o de classe. O m=E9todo de nome
 * "init" ser=E1 usado como construtor da classe.
 * <p>
 * Exemplo da cria=E7=E3o de uma classe:
 * <pre>
 * c1 =3D function() {this.__init__(arguments);}
 * c1.Class();
 * c1.prototype.init =3D function( msg ) {
 *   this.msg =3D msg;
 * }
 * var obj =3D new c1( "Teste Objeto" );
 * </pre>
 *
 * @return Function
 */

Output HTML:

   <A NAME=3D"Class"><!-- --></A>
   <H3>Class</H3>
   <PRE>Object <B>Class</B>()</PRE>

      <UL>Fun=E7=E3o para cria=E7=E3o de classe. O m=E9todo de nome
 "init" ser=E1 usado como construtor da classe.
 <p>
 Exemplo da cria=E7=E3o de uma classe:
 <pre>

 c1 =3D
function() {}
 c1.Class();
 c1.prototype.init =3D
function( msg ) {}
 var obj =3D new c1( "Teste Objeto" );
 </pre></UL>


I think its a bug, ins't?

--
Marco Catunda