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

Re: [Jsdoc-user] RECURSION in JSDoc.pm

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

Hi Marcel,

> I'm using the current JSDoc-1.10.2 and
> the current perl v5.8.8 built for i586-linux-thread-multi.
>
> If i use RECURSION=2 JSDoc works fine
> but for any value > 2 it fails.
>
> Is there any work around / patch ... i can try to get
> JSDoc running with my Javascript?
> Does it really help if i build the perl 5.8.8 from source
> myself as stated in the FAQ?

The only workaround that I've encountered that works (sometimes) is a
new build of perl. There are of course no guarantees that a new build
will help, but having a more "basic" build seems to generally improve
the situation. In the end, this is a bug in perl itself (perl should
*never* segfault on something that is written in pure perl), so the
options are pretty limited.

Something else you may want to check out is the JsDoc Toolkit
(www.jsdoc.info), which is a newer JavaScript documenting framework
with much better support for dynamic JavaScript and no problems like
this segfault one.

Regards,

Gabriel

[Jsdoc-user] RECURSION in JSDoc.pm

[Marcel R. <mr...@ma...>]

Hi,

again the recursion issue ...

I'm using the current JSDoc-1.10.2 and
the current perl v5.8.8 built for i586-linux-thread-multi.

If i use RECURSION=2 JSDoc works fine
but for any value > 2 it fails.

Is there any work around / patch ... i can try to get
JSDoc running with my Javascript?
Does it really help if i build the perl 5.8.8 from source
myself as stated in the FAQ?

Thanks a lot,
Marcel

--
http://watchee.net

Re: [Jsdoc-user] Documenting Name Spaces

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

Hi Mark,


> I am new to JSDoc and I have not been able to find a way for it to
> produce documentation based on namespaces.
> Here is an example of how we are defining namespaces.Jsdoc fails to
> document this no matter which options I try.
> Since this is a valid way to define namespaces then Jsdoc should support it.

This is indeed a valid way to define a namespace in JavaScript. On the
other hand, it could also be looked at as a valid way to define a
variable, or a Singleton instance, or any other number of things. The
point I'm getting at here is that JavaScript is a very flexible
language, and JSDoc is somewhat limited in what it knows how to deal
with.

The good news is that there is a newer documentation tool that is
somewhat similar to JSDoc which may be able to handle this: JsDoc
Toolkit (http://www.jsdoc.info). JSDoc actually isn't really being
actively maintained anymore, and support for constructs like this
certainly aren't planned to be implemented, so you'll probably have a
lot more luck with JsDoc Toolkit.


Regards,

Gabriel

[Jsdoc-user] Documenting Name Spaces

[Mark M. <mmi...@ri...>]

I am new to JSDoc and I have not been able to find a way for it to
produce documentation based on namespaces.
Here is an example of how we are defining namespaces.Jsdoc fails to
document this no matter which options I try.
Since this is a valid way to define namespaces then Jsdoc should support it.

         
/**
 *  Survey System name space
 *
 * @version      1.5
 * @author       Mark Mitchell <mmi...@ri...>
 * @name         Survey System
 * @constructor
 *
 */
var SS = {   

    /**
     * Survey system form object set in pageInit()
     */
    objForm : null,
 
    /**
     * Page init function
     *
     * @access  public
     * @since    1.0
     * @return   void
     */
    pageInit : function() {
       this.objForm = document.forms[0];
       return;
    }
}

[Jsdoc-user] hello

[<gon...@gm...>]

DQoNCg0KDQoNCrmotcLOsA0KMjAwNy0wOS0wNg0K

[Jsdoc-user] jsdoc with recursive option

[Jacques G. <jac...@ge...>]

Hi All,

I'm currently looking at Jsdoc.

My JavaScript code is distributed in a tree structure and contain no 
tag with '@'.

When I run
jsdoc.pl -r dir_that_contain_tree_structure
I can see that jsdoc recognize each file in it, but "js_docs_out" is empty.

If I run it over just one file, it produce docs.

Could you explain me why "js_docs_out" stay empty when I run jsdoc 
over a folder ?

Thanks,


Jacques Guellec

[Jsdoc-user] Does JSDoc support documenting JSON classes

[Ahmed J. <ahm...@gm...>]

If I have the following singleton object, JSDoc doesn't produce any
documentation for it?

/**
 * My class foo
 */
var foo = {
  /**
   * Bar function
   */
  bar: function() {
  }
}

Does JSDoc only work with functions defined starting with the function
keyword?

Re: [Jsdoc-user] does JSDoc work in an IDE

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

Hi Kate,

> I have been experimenting with using JSDoc to document my company's
> JavaScript API. All of the developers around here keep asking me if this
> JSDoc API output can be used with their IDEs (most use Eclipse with the
> JavaScript plug-in). As they are writing their code they want like an
> auto-suggest ability from JSDoc from within Eclipse. So if they are
> writing an API like nlapiCreateForm or nlapiGetNewRecord they will be
> able to tell which arguments are available, etc.
>
> You pretty much already said that this is not possible using JSDoc, but
> I wasn't sure if I had phrased my original question in a way that fully
> explained what I was looking for.


Yes, that's how I understood your question originally, so my answer
still stands. I can imagine that this kind of thing would be very
helpful, and it certainly could be created, but I'm not aware of
anything like this that's available right now.

Regards,

Gabriel

Re: [Jsdoc-user] does JSDoc work in an IDE

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

Hi Kate,

>
> Is it possible to import JSDoc into Eclipse (or any other IDE) for API
> auto-suggestions, etc?
>
>

No, I'm not aware of anything like this, although it certainly sounds
as though it could be useful.

Regards,

Gabriel

[Jsdoc-user] does JSDoc work in an IDE

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

Is it possible to import JSDoc into Eclipse (or any other IDE) for API
auto-suggestions, etc?

=20

Thanks,

Kate

Re: [Jsdoc-user] prototype object parsing bug

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

On 7/17/07, Cameron Davison <cam...@gm...> wrote:
> using perl v5.8.7 built for cygwin-thread-multi-64int
> using jsdoc v1.10.2
>
> The line following the comment "#Alter the prototype-initialization
> blocks" kills the running perl execution while trying to parse a large
> object. I have attached some source code that is completely contrive,
> just to illustrate the point. If you comment out the line that says it
> causes an error it works fine, but if you leave it in it make it too
> large and causes perl to crash without a stack trace.
>

Yes, this is an unfortunate situation that seems to occur from time to
time. I can't say much more than that it's a bug in perl, as JSDoc is
pure perl, and perl should never segfault. There's a bit more
information on this issue on the third FAQ at
<http://jsdoc.sourceforge.net/#faq>.

Regards,

Gabriel

[Jsdoc-user] prototype object parsing bug

[Cameron D. <cam...@gm...>]

using perl v5.8.7 built for cygwin-thread-multi-64int
using jsdoc v1.10.2

The line following the comment "#Alter the prototype-initialization
blocks" kills the running perl execution while trying to parse a large
object. I have attached some source code that is completely contrive,
just to illustrate the point. If you comment out the line that says it
causes an error it works fine, but if you leave it in it make it too
large and causes perl to crash without a stack trace.

Re: [Jsdoc-user] JsDoc toolkit 5.2

[Eefje C. <Eef...@ar...>]

 Thanks for your answer!

Regarding my first issue. It works if I only put '@field' instead of
'@field employeeId'.

Kr,
Eefje.

-----Original Message-----
From: Michael Mathews [mailto:mi...@gm...]=20
Sent: woensdag 27 juni 2007 14:29
To: Eefje Colman; Jsd...@li...
Subject: Re: [Jsdoc-user] JsDoc toolkit 5.2

This should be posted to the JsDoc Toolkit list, not here. And you are
not using version 5.2, you are using version 0.5.2 beta (I suspect).
Version 1.0 is going to be released in the next couple of weeks, with
API changes, at which time the 0.5 betas will become deprecated, so I
don't want to publicly answer your question about how to apply the JDTK
tags *yet*.

In short, the 1.0 release will more closely follow the tags defined in
ScriptDoc, see: http://www.scriptdoc.org/specification.htm

If you send me a bit of your actual code I can use it in a test case and
tell you exactly how to tag it. A general announcement, and
documentation, will come in early July.

Regards,
Michael

On 27/06/07, Eefje Colman <Eef...@ar...> wrote:
>
>
> Hi,
>
> In order to get rid of some 'recursive' problems using JsDoc from=20
> sourceforge, I installed JsDoc toolkit 5.2.
> This solves my problem regarding recursion, but some tags aren't=20
> recognized in the toolkit.
>
> For example:
>
> 1.
>
>
> /**
>
> * id of the employee selected (could be logged user).
>
> * @field employeeId
>
> * @type String
>
> */
>
> This isn't recognized, although @field should work, I assume.
>
> The @type tag was also usefull, so I could be redirected to the String

> class...
>
> 2.
>
> Are there alternatives for @type , @see, @return, ... in JsDoc toolkit
?
>
>
>
> Kind Regards,
>
> Eefje.
> ----------------------------------------------------------------------
> --- 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=20
> 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
>
>

Re: [Jsdoc-user] JsDoc toolkit 5.2

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

This should be posted to the JsDoc Toolkit list, not here. And you are
not using version 5.2, you are using version 0.5.2 beta (I suspect).
Version 1.0 is going to be released in the next couple of weeks, with
API changes, at which time the 0.5 betas will become deprecated, so I
don't want to publicly answer your question about how to apply the
JDTK tags *yet*.

In short, the 1.0 release will more closely follow the tags defined in
ScriptDoc, see: http://www.scriptdoc.org/specification.htm

If you send me a bit of your actual code I can use it in a test case
and tell you exactly how to tag it. A general announcement, and
documentation, will come in early July.

Regards,
Michael

On 27/06/07, Eefje Colman <Eef...@ar...> wrote:
>
>
> Hi,
>
> In order to get rid of some 'recursive' problems using JsDoc from
> sourceforge, I installed JsDoc toolkit 5.2.
> This solves my problem regarding recursion, but some tags aren't recognized
> in the toolkit.
>
> For example:
>
> 1.
>
>
> /**
>
> * id of the employee selected (could be logged user).
>
> * @field employeeId
>
> * @type String
>
> */
>
> This isn't recognized, although @field should work, I assume.
>
> The @type tag was also usefull, so I could be redirected to the String
> class...
>
> 2.
>
> Are there alternatives for @type , @see, @return, ... in JsDoc toolkit ?
>
>
>
> Kind Regards,
>
> Eefje.
> -------------------------------------------------------------------------
> 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] JsDoc toolkit 5.2

[Eefje C. <Eef...@ar...>]

Hi,
=20
In order to get rid of some 'recursive' problems using JsDoc from
sourceforge, I installed JsDoc toolkit 5.2.
This solves my problem regarding recursion, but some tags aren't
recognized in the toolkit.
=20
For example:
=20
1.
/**

* id of the employee selected (could be logged user).

* @field employeeId

* @type String=20

*/=20

This isn't recognized, although @field should work, I assume.

The @type tag was also usefull, so I could be redirected to the String
class...

2.

Are there alternatives for @type , @see, @return, ... in JsDoc toolkit ?

=20

Kind Regards,

Eefje.

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

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

I will be out of the office starting  06/26/2007 and will not return until
07/11/2007.

I will respond to your message when I return.

Re: [Jsdoc-user] recognize "different" way of coding

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

Hi,

> We are currently working in a project using Javascript for coding and JSDoc
> for our documentation.
> We are using a lot of "extends" to build up a hierarchie, but we are not
> using the "standard" mechanisms to realize this extend but a self written
> function to check dependencies etc.

As you've already noticed, this style of coding unfortunately isn't
supported by JSDoc. Although it would be potentially possible to alter
JSDoc to support this style of code, I would instead suggest that you
check out the JsDoc Toolkit (http://www.jsdoc.info). This is kind of a
newer and much more flexible version of JSDoc, and should support
these kinds of constructs with much less effort on your part.

Regards,

Gabriel

[Jsdoc-user] recognize "different" way of coding

[Thomas P. <mad...@ya...>]

Hello.

We are currently working in a project using Javascript for coding and JSDoc for our documentation. 
We are using a lot of "extends" to build up a hierarchie, but we are not using the "standard" mechanisms to realize this extend but a self written function to check dependencies etc.
An example can be seen here:


/**
 * Module base class. All modules defined in the application inherit from this class.
 * @namespace aria.ui
 * @class Module
 * @extends aria.lang.JsObject
 * @constructor
 */
aria.ui.Module = function() {

    /**
     * store the allowed index per panel
     * @property _index
     * @type Array
     * @private
     */
    this._index = [];
}

a.extend("aria.ui.Module", "aria.lang.JsObject", {
    /**
     * Protected _index setter
     * @method setIndex
     * @param {String} index  The Index to use for this panel
     */
    setIndex: function(target,i) {
        if(!('_index' in this))this._index = [];
        this._index[target] = i;
    },
    
    /**
     * Protected _index getter
     * @method setId
     * @param {String} index  The Index to use for this panel
     */
    getIndex: function(target) {
        if(!('_index' in this))this._index = [];
            return this._index[target];
    }
);


As you see the function a.extend realize all the stuff. 
My question is now, if there is any possibility to let JSDoc recognize the inner methods just like "setIndex" or "getIndex" as member of the class "aria.ui.Module".

We already tried some modifications in the code as well as modifying the parameters passed to jsdoc but couldn't figure out a solution.

Thanks for your help

Best regards

Thomas Pietsch





      __________________________________
Machen Sie Yahoo! zu Ihrer Startseite. Los geht's: 
http://de.yahoo.com/set

Re: [Jsdoc-user] Unable to process a file

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

Hi Yvan,

> I am new to JSDoc and I have tried to generate documentation using JSDoc,
> unfortunately I didn't succeed. JSDoc said that there is nothing to
> document.
>
> Did I made some syntax error in JSDoc, I am using prototypejs to generate my
> classes, is it incompatible with JSDoc ? Is there somewhere where I can get
> a correct sample to start with ?

Thanks for your excellent description of the problem. The issue here
is that JSDoc doesn't support the code as it's written (using
prototype.js). JSDoc was originally written to deal more with the "old
school" assignment of functions to other function prototypes.

The good news is that I believe that the newer incarnation of JSDoc
(JsDoc Toolkit, at http://jsdoc.info), does support more dynamic
constructs like the ones in your code. I suggest you check it out, as
it will most likely solve the problems you're encountering with JSDoc.

Regards,

Gabriel

[Jsdoc-user] JSDoc multi-line comments question

[Bob J. <bj...@go...>]

I'm supporting a tool that parses JSDoc comments for, amongst other things,
the type info.  Since we are in the early stages of getting this posted back
to Mozilla, I'd like to preserve compatibility with JSDoc.  I also can't get
the necessary Perl scripts installed on my local machine to just poke at it
and see what happens.

The questions is, is the following valid:

/**
 @param {myType|
                Number} myParam blah blah blah
 */
function foo(myParam) ...


Can you break a tag in mid-curly?

And then what about:

/**
 @param {types}
                 myParam blah blah blah
 */
function foo(myParam) ...

Does this work?

Thanks,
Bob Jervis

[Jsdoc-user] @param problem

[Avancerad W. <td...@gm...>]

An error, like in this code, causes the JSDoc for the whole class to
crash. Wouldn't it be nice if JSDoc notified me OR just at least
ignored the the typo? The error is "@param {Observer)"

/**
* Registers a Observer
* @param {Observer) observer The observer to register.
*/
this.registerObserver = function(observer){
	observerArr.push(observer);
}

Re: [Jsdoc-user] generation not done when adding particular methods to .js-source file

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

Hi Eefje,

It sounds to me like perl is segfaulting while you're running JSDoc.
This will be the case if the tool just dies without an error message
or anything.

This is a pretty tough problem to deal with (as there aren't any
really cut-and-dried solutions), but I would suggest taking a look at
FAQ #3 at <http://jsdoc.sourceforge.net/#faq>. If you try one of the
fixes there, it should (hopefully) take care of this.

Regards,

Gabriel


On 5/14/07, Eefje Colman <Eef...@ar...> wrote:
>
>
> Hi,
>
> I'm using JSDoc (and ActivePerl) on Windows XP and so far generating my API
> didn't give any problems.
>
> In my batch-file I specify a lot of folders (+/- 20 folders) with .js-source
> files.
> When adding one specific folder , the documents aren't generated anymore.
> I've checked several things and when I exclude some methods from my
> .js-source file in that folder, the documents are generated again.
> But I don't see the problem... (nor solution)
>
> For example. When I add this in my javascript, no generation is done :
>
>
> /**
>
> * open the monthly calendar
>
> * @method open
>
> * @type void
>
> */
>
> this.open = function(){
>
> this.isOn = true;
>
> $(this.getTargetDiv()).style.display = "block";
>
> }
>
> if I remove it.... the generation is done .
>
> To give you an idea... this source file contains +/- 1900 lines of code...
> and this little block of code stops the generation...
>
> -------------------------------------------------------------------------
> 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
>
>

Re: [Jsdoc-user] generation not done when adding particular methods to .js-source file

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

Hi Eefje,

I don't actually see @method listed as part of the JSDoc.pm syntax,  
though Gabriel may have just neglected to add it to the docs. Have  
you tried @member instead?

Regards,
Michael

On 14 May 2007, at 11:21, Eefje Colman wrote:

> Hi,
>
> I'm using JSDoc (and ActivePerl) on Windows XP and so far  
> generating my API didn't give any problems.
>
> In my batch-file I specify a lot of folders (+/- 20 folders)  
> with .js-source files.
> When adding one specific folder , the documents aren't generated  
> anymore.
> I've checked several things and when I exclude some methods from  
> my .js-source file in that folder, the documents are generated again.
> But I don't see the problem... (nor solution)
>
> For example. When I add this in my javascript, no generation is done :
> /**
>
> * open the monthly calendar
>
> * @method open
>
> * @type void
>
> */
>
> this.open = function(){
>
> this.isOn = true;
>
> $(this.getTargetDiv()).style.display = "block";
>
> }
>
> if I remove it.... the generation is done .
>
> To give you an idea... this source file contains +/- 1900 lines of  
> code... and this little block of code stops the generation...
>
>
> ---------------------------------------------------------------------- 
> ---
> 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] generation not done when adding particular methods to .js-source file

[Eefje C. <Eef...@ar...>]

Hi,
=20
I'm using JSDoc (and ActivePerl) on Windows XP and so far generating my
API didn't give any problems.
=20
In my batch-file I specify a lot of folders (+/- 20 folders) with
.js-source files.
When adding one specific folder , the documents aren't generated
anymore.=20
I've checked several things and when I exclude some methods from my
.js-source file in that folder, the documents are generated again.
But I don't see the problem... (nor solution)
=20
For example. When I add this in my javascript, no generation is done :
/**

* open the monthly calendar

* @method open

* @type void

*/=20

this.open =3D function(){

this.isOn =3D true;

$(this.getTargetDiv()).style.display =3D "block";

}

if I remove it.... the generation is done .

To give you an idea... this source file contains +/- 1900 lines of
code... and this little block of code stops the generation...

=20

Re: [Jsdoc-user] Large files

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

> 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.


Hi Dave,

This is (unless I'm terribly mistaken) a case of perl segfaulting; the
segfaults seem to be directly related to the recursive regexes that
are used within JSDoc.

This all seems to be closely related to different builds of perl on
different platforms. Unfortunately, I can't say any specific version
of perl on a specific platform will definitely work.

Another approach is messing around with the $RECURSION variable in
JSDoc.pm, as detailed in FAQ #3 at
<http://jsdoc.sourceforge.net/#faq>.

Apart from that, there (unfortunately) doesn't seem to be a clear
solution for this issue on all platforms.

Regards,

Gabriel