Mark Wubben | 22 Jul 2012 23:39
Gravatar

Doc parser & API viewer questions / feedback

Some questions and general feedback about the doc parser, as I was trying to get the API docs for
dojo/promise come out as nicely as possible. Documentation generated according to the instructions at <https://github.com/wkeese/api-viewer/>.

Here I'm trying to define the `promise` property of Deferred:
<https://github.com/novemberborn/dojo/compare/docs#L0L94>. My comments are never included in the
documentation. If I define the property elsewhere, say within a block like this, they are included:

    /*=====
    lang.extend(Deferred, {
      // promise:
      //		…
      promise: null
    });
    =====*/

The assignment to `var reject` here causes `instance` to be one of the return values:
<https://github.com/novemberborn/dojo/compare/docs#L0L179>, even though I've declared the
return value.

Return statements like these don't get picked up correctly:
<https://github.com/novemberborn/dojo/compare/docs#L0L112>. Adding `// Boolean` at the end
doesn't work. Perhaps given the triple equals the boolean could even be deduced.

I'd like to be able to link to other pages, e.g. by including [dojo/errors/CancelError] in the documents.
I've done this in another project that uses Marked. Is this already included somewhere but with different
syntax? If not, where could I include it? In fact, which repo is the actual one that's being used?
<https://github.com/wkeese/api-viewer/> says to use <https://github.com/wkeese/js-doc-parse/tree/all-my-changes>.

trace() takes zero or more arguments, of any type. Can this be expressed? <https://github.com/novemberborn/dojo/compare/docs#L6L32>

(Continue reading)

Bill Keese | 23 Jul 2012 04:26
Favicon
Gravatar

Doc parser & API viewer questions / feedback

Thanks for the feedback.

On Mon, Jul 23, 2012 at 6:39 AM, Mark Wubben <mark <at> novemberborn.net> wrote:
Here I'm trying to define the `promise` property of Deferred: <https://github.com/novemberborn/dojo/compare/docs#L0L94>. My comments are never included in the documentation. If I define the property elsewhere, say within a block like this, they are included:

Looks like a bug, please file it at https://github.com/csnover/js-doc-parse/issues



The assignment to `var reject` here causes `instance` to be one of the return values: <https://github.com/novemberborn/dojo/compare/docs#L0L179>, even though I've declared the return value.

Looks like a bug, please file it at https://github.com/csnover/js-doc-parse/issues

 

Return statements like these don't get picked up correctly: <https://github.com/novemberborn/dojo/compare/docs#L0L112>. Adding `// Boolean` at the end doesn't work. Perhaps given the triple equals the boolean could even be deduced.

and https://github.com/csnover/js-doc-parse/issues/54 but you can file another ticket if you like.



I'd like to be able to link to other pages, e.g. by including [dojo/errors/CancelError] in the documents. I've done this in another project that uses Marked. Is this already included somewhere but with different syntax? If not, where could I include it?

You mean in the summaries/descriptions/etc?   Not implemented, but I'd certainly like to add that feature.    Which syntax is good?   Or, auto-detect?   I thought about auto-detecting, like how editors etc. auto-detect URLs, and I guess it's easy to detect something like dijit/form/Button or dijit/Tree.TreeNode, but it gets a more complicated for something like dojo/dom.byId() or dojo/dom.byId(id, doc), because of the parentheses.

 
In fact, which repo is the actual one that's being used? <https://github.com/wkeese/api-viewer/> says to use <https://github.com/wkeese/js-doc-parse/tree/all-my-changes>.

Right.   The api-viewer requires a bunch of changes I've made that Colin hasn't merged in yet, so for now you need to use my version of js-doc-parse.

 

trace() takes zero or more arguments, of any type. Can this be expressed? <https://github.com/novemberborn/dojo/compare/docs#L6L32>

Not that I know of.    That would be a nice enhancement.

 

Why do non-constructor modules have a Methods section? E.g. the doc page for dojo/promise/first. There are no methods on first().

Well, dojo/dom is a non-constructor, and it makes sense there to have a methods sections, right?    But I agree the method section should be suppressed if there are no methods, like for first(), so please file a ticket at https://github.com/wkeese/api-viewer/issues
 

Are these kinds of blocks even needed?

    // module
    //          dojo/promise/all


I find them useful for debugging.    Not all debuggers make the module name easy to see.
 

When modules are shown in the api viewer, and the beginning of their description matches the summary, does the summary need to be shown? Or should the description not include the summary? See the doc page for dojo/promise/instrumentation.

As you realized, I decided to display both the summary and the description for modules, to err on the side of caution, since some of the modules assumed that both would be shown.    The safest thing to do nowadays for both modules and methods is to put all the info in the summary, and get rid of the description altogether.   The API viewer is smart enough to only display the first sentence in the "methods summary" section, same as javadoc does.   I meant to send mail about this earlier.



In <https://github.com/novemberborn/dojo/compare/docs#L7L23> I'd like to assign an `any` type to `valueOrPromise` but that completely messes up the return value.


Although there are already a number of tickets open about return types, I guess to be safe you should file another ticket at https://github.com/csnover/js-doc-parse/issues.
_______________________________________________
dojo-contributors mailing list
dojo-contributors <at> mail.dojotoolkit.org
http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors
Bill Keese | 24 Jul 2012 15:25
Favicon
Gravatar

Re: Doc parser & API viewer questions / feedback

I decided to do this feature.   You can see it working at http://bill.dojotoolkit.org/api/1.8/dojo/_base/Deferred, automatically detecting module references and turning them into links.

On Mon, Jul 23, 2012 at 6:39 AM, Mark Wubben <mark <at> novemberborn.net> wrote:
I'd like to be able to link to other pages, e.g. by including [dojo/errors/CancelError] in the documents. I've done this in another project that uses Marked. Is this already included somewhere but with different syntax? If not, where could I include it? In fact, which repo is the actual one that's being used? <https://github.com/wkeese/api-viewer/> says to use <https://github.com/wkeese/js-doc-parse/tree/all-my-changes>.

_______________________________________________
dojo-contributors mailing list
dojo-contributors <at> mail.dojotoolkit.org
http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors
Bill Keese | 24 Jul 2012 16:41
Favicon
Gravatar

Re: Doc parser & API viewer questions / feedback

PS: There's no automatic hyperlinking for global variables (ex: dojo.replaceClass or dijit.form.Button); your dojodoc comments to list things as MIDs (ex: dijit/form/Button) or MID+property (ex: dojox/gfx/shape.Circle).

On Tue, Jul 24, 2012 at 10:25 PM, Bill Keese <bill <at> dojotoolkit.org> wrote:
I decided to do this feature.   You can see it working at http://bill.dojotoolkit.org/api/1.8/dojo/_base/Deferred, automatically detecting module references and turning them into links.

On Mon, Jul 23, 2012 at 6:39 AM, Mark Wubben <mark <at> novemberborn.net> wrote:
I'd like to be able to link to other pages, e.g. by including [dojo/errors/CancelError] in the documents. I've done this in another project that uses Marked. Is this already included somewhere but with different syntax? If not, where could I include it? In fact, which repo is the actual one that's being used? <https://github.com/wkeese/api-viewer/> says to use <https://github.com/wkeese/js-doc-parse/tree/all-my-changes>.


_______________________________________________
dojo-contributors mailing list
dojo-contributors <at> mail.dojotoolkit.org
http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors

Gmane