Documenting the Revealing Module Pattern
Roger
I may be missing something obvious, but I can't figure out how to make
JsDoc Toolkit understand scripts that use the Revealing Module Pattern
described here:
http://www.wait-till-i.com/2007/08/22/again-with-the-module-pattern-reveal-something-to-the-world/
Here's a dummy example of the pattern I would like to document:
/**
* Function description
*/
var myFunction = function () {
/**
* Description of the init method
*/
function init(someParameter) {
// Do stuff
}
/**
* Description of the methodOne method
*/
function methodOne() {
// Do other stuff
}
return {
init: init
};
}();
My problem is that I can't get JsDoc to recognise the nested
functions. How would one use JsDoc Toolkit to document this pattern?
Apologies if this has been mentioned somewhere already.
/Roger
Michael Mathews
I admit this is a complicated issue, so your question is useful;
thanks for asking it.
Firstly, the methods "init" and "methodOne" are considered "inner
methods" by JsDoc Toolkit and before Version 2 they were invisible by
the parser by design. One of the new capability of Version 2 is that
the parser now has the ability "see" inner functions.
So the first thing you'll need to do is to use the Preview release of
Version 2. If you aren't able/willing to do that, I can suggest some
hacks you can use to get around the limitation, but I would suggest
you don't use them if you don't absolutely have to.
Assuming you do decide to use Version 2, you'll need to add the -p
flag to your command line because JsDoc Toolkit considers inner
functions to be "private" and therefore won't show them without -p.
Hope that helps but feel free to follow up if I haven't answered your
question fully.
In the very latest revision of the Version 2 branch of JsDoc Toolkit
(541) you can document the "borrowing" of an inner method as a public
method, similar to what you've shown in your example code. That would
be tagged like so:
/**
* Namespace description
* @namespace
* @borrows myFunction-init as this.init
*/
myFunction = function () {
/**
* Description of the init method
*/
function init(someParameter) {
// Do stuff
}
/**
* Description of the methodOne method
*/
function methodOne() {
// Do other stuff
}
return {
init: init
};
}();
Again, this requires the -p flag to make the inner functions visible,
and thus borrowable. I'm not entirely happy with that, because you
should be able to explicitly borrow a method whether it appears in
the documentation or not in its original form. Expect the ability to
borrow private methods without the -p flag in the final Version 2
release.
Kind Regards,
Michael
PS I hadn't heard of the Revealing Pattern before your email, even
though I'm currently reading the Apress book _Pro JavaScript Design
Patterns_. For the benefit of anyone else who is curious, as I was, I
found a good description of it here:
Michael Mathews
The missing link is http://www.klauskomenda.com/code/javascript-
programming-patterns/#revealing
Roger Johansson
On 21 mar 2008, at 13.03, Michael Mathews wrote:
> Assuming you do decide to use Version 2, you'll need to add the -p
> flag to your command line because JsDoc Toolkit considers inner
> functions to be "private" and therefore won't show them without -p.
Ah, that did it. I overlooked the -p flag. Thanks!
> In the very latest revision of the Version 2 branch of JsDoc Toolkit
> (541) you can document the "borrowing" of an inner method as a public
> method, similar to what you've shown in your example code. That would
> be tagged like so:
I'm not sure I'm doing it right. Adding "@borrows myFunction-init as
this.init " makes myFunction appear twice in the Class index of the
documentation, and the "init" method is still listed as private.
Would adding a @public tag to version 2 be an option at all? Since
there is a @private tag it sort of makes sense to have a @public tag
as well, at least to me :-). My example would then look like this:
/**
* Namespace description
* @namespace
*/
myFunction = function () {
/**
* Description of the init method
* @public
*/
function init(someParameter) {
// Do stuff
}
/**
* Description of the methodOne method
*/
function methodOne() {
// Do other stuff
}
return {
init: init
};
}();
/Roger
Michael Mathews
On 22 Mar 2008, at 9:10, Roger Johansson wrote:
> I'm not sure I'm doing it right. Adding "@borrows myFunction-init as
> this.init " makes myFunction appear twice in the Class index of the
> documentation, and the "init" method is still listed as private.
There is a bug (or maybe an "unexpected feature"?) in Version 2 that
can cause a symbol to be documented twice under circumstances such as
this. I believe it is resolved in the latest revision now in the
repository, but I'd like to have a test case to prove that. Can you
send me the code you use to get the double documentation? Or, if it's
just the same code I sent you, then no worries: it's already fixed.
> Would adding a @public tag to version 2 be an option at all? Since
> there is a @private tag it sort of makes sense to have a @public tag
> as well, at least to me :-). My example would then look like this:
>
> /**
> * Namespace description
> * @namespace
> */
> myFunction = function () {
> /**
> * Description of the init method
> * @public
> */
> function init(someParameter) {
> // Do stuff
> }
> /**
> * Description of the methodOne method
> */
> function methodOne() {
> // Do other stuff
> }
> return {
> init: init
> };
> }();
>
This is an interesting suggestion, and something similar has been
suggested before. It certainly makes the doclet look nice and tidy
and is more intuitive than a class borrowing a method from itself.
Just to clarify though, would this new tag have the effect of always
documenting a public member *with the same name* as the inner member?
Also would the documented member be assumed to be an *instance
member* by default?
That is, example A and B would be functionally equivalent?
// EXAMPLE A
function Foo() {
/** @public */
function bar(){}
}
// EXAMPLE B
function Foo() {
this.bar = function(){}
}
While example C and D would also be functionally equivalent?
// EXAMPLE C
function Foo() {
/**
@static
@public
*/
function bar(){}
}
// EXAMPLE D
function Foo() {
}
Foo.bar = function(){}
For simplicity's sake there would be no way to say
"@publicButWithThisName barBar" - the name of the public member will
always be the name of the inner member.
It would be helpful if this were added as a feature request to the
issue tracker:
http://code.google.com/p/jsdoc-toolkit/issues/list
Kind Regards,
Michael
Roger Johansson
On 22 mar 2008, at 12.17, Michael Mathews wrote:
> Can you
> send me the code you use to get the double documentation? Or, if it's
> just the same code I sent you, then no worries: it's already fixed.
I got the result with the code you sent me, so I'll consider that bug/
unexpected feature resolved :-).
> Just to clarify though, would this new tag have the effect of always
> documenting a public member *with the same name* as the inner member?
Speaking for myself, yes. Perhaps there are cases when you want a
public member to have a different name, but I haven't run into one yet.
> Also would the documented member be assumed to be an *instance
> member* by default?
I'm not sure. Most of the time I work with "one off" functions rather
than classes that need instantiation, so I would prefer if someone who
is more experienced with object oriented JavaScript would comment on
that.
> It would be helpful if this were added as a feature request to the
> issue tracker:
> http://code.google.com/p/jsdoc-toolkit/issues/list
Done!
/Roger