Comments (8)
This also holds for "description" and "example", not only the "summary" part of the doc comments.
from js-doc-parse.
No doc parser ever supported these, someone just…started adding them to the code for some reason.
The value of the module is the thing that should have the summary on it. I don’t see being able to do both as a possible thing because the summary and description of a module are imbued by whatever the value of the module happens to be. I realise this is kind of crappy about summarising things like NodeList-fx but I’m not really sure it is important or relevant to try to support this. Thoughts?
from js-doc-parse.
@csnover there are modules that needs to be required to enable a particular feature but for which the return value is rather meaningless. An example is dojox/mobile/compat. It needs to be included so that compatibility with desktop browser of dojox/mobile is enabled. It returns dojox/mobile for convenience and also because it adds some compatibility method on it but that return value is in most cases not really of interest. What is of interest is to know that when you include it you will enable the compatibility layer. That's why I think module documentation makes sense. Or any other solution that would allow to document this.
from js-doc-parse.
From dojox.mobile's point of view, what is important for this release is to have some way, any way, to get documentation for a module which doesn't define any class.
So do you mean that the summary on the value of the module would work already? Or that it may work in the near future?
With a freshly updated checkout of js-doc-parse, I've tried to place documentation for dojox/mobile/compat at 3 different places:
define([...], function(...){
// module:
// dojox/mobile/compat
// summary:
// foo1
// description:
// foo1
// summary:
// foo2
// description:
// foo2
var dm = lang.getObject("dojox.mobile", true);
[...]
// summary:
// foo3
// description:
// foo3
return dm;
});
And I don't get any of these "foo" pieces in the generated XML.
from js-doc-parse.
No doc parser ever supported these
It's natural that we've never supported this before because we've never had an AMD doc parser before. But I agree that it's not needed in most cases.
I realise this is kind of crappy about summarising things like NodeList-fx
Right, this is probably the biggest issue. (@cjolif - the compat.js example is the same as the NodeList-fx example, both of those modules extend other modules.)
The other issue is the one I mentioned originally, where the module returns a scalar value or strange value:
define([], function(){
// summary:
// This comment gets lost
return 123;
});
or perhaps something like:
define([], function(){
// module:
// jsonparse
// summary:
// function to parse json
return JSON ? JSON.parse : function(){ ... };
});
The workaround below will make the summary show up, but it loses the metadata about the module's true value.
define([], function(){
/*=====
return {
// summary:
// does this show up?
};
=====*/
return 123;
});
(In the above case it says that the module's value is an object with no properties, whereas actually it's a number.)
PS: I was also worried about plugins but I just tested and they seem to work fine, since they return a hash which can enclose a summary:
define(...
return {
// summary: ...
PPS: I sent mail to this list about this, but no response.
from js-doc-parse.
Right, the workaround you mention, Bill, does the trick for our dojox/mobile/compat, in the sense both the summary and descriptions are now in the XML. Thanks!
In this particular case the lost metadata for the return value is not that much an issue, since users are not really supposed to do something with the return value of dojox/mobile/compat. Now, of course, if the API doc will include false information about the return value, this is not optimal. But at least we have a way to put documentation on our compat stuff.
from js-doc-parse.
Good, that may be the best compromise for the 1.8 release.
And at the risk of stating the obvious, you can of course describe the real return value in the summary or description.
from js-doc-parse.
(in progress comment)
Modules difficult/impossible to work without module level summary (or some other feature):
- exports modules (dojo/dom-attr, etc.) see #42
- dojo/main - returns the dojo/_base/kernel object but the summary is importantly different: it should say that dojo/main forces all the dojo/_base modules to be loaded
- dojo/on, dojo/has: these module return a function with other functions hanging off of it (ex: on() and on.pausable(), has() and has.add()). Thus the description for the module and the top function are different. Although even if the doc parser could remember both summaries I don't see how the viewer would display them concurrently and coherently.
- dojo/router, dojo/sniff - adding a description means losing the type information (ie, that dojo/router is an instance of dojo/router/RouterBase, that dojo/sniff returns has)
from js-doc-parse.
Related Issues (20)
- return query(...) // dojo/NodeList not working HOT 2
- property's summary gets assigned to the property's value HOT 4
- monkey-patched functions erase original function doc HOT 4
- fx.js makes other file lose easing and duration kwargs definition HOT 3
- kwargs definition using declare() to extend from plain function() broken HOT 1
- inline expansion of union types with kwargs doesn't work HOT 2
- comment on line declaring export variable masks summary HOT 3
- fragile regex for union types HOT 1
- inline return types often ignored HOT 1
- properties added from one module to another sometimes don't show up HOT 1
- dojodoc for properties with dashes ignored HOT 1
- js-doc-parser errors HOT 2
- Ubuntu/Canonical process.execPath = /usr/bin/nodejs HOT 1
- Add support for documenting attach points and attach events HOT 2
- tree.json no longer generated HOT 1
- ERR: TypeError: Object true has no method 'match' HOT 6
- parse.bat config = ./config.js produces error "ERR: TypeError: Object true has no method 'match'" HOT 1
- dynamic AMD require
- js-doc-parse traces when require()ing external url
- UMD modules HOT 1
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from js-doc-parse.