Types of extracted default args are unambiguous in doclets after all. Get them right in extracted formal param lists. Fix #56. #57
Conversation
… Get them right in extracted formal param lists. Fix #56. JSDoc doesn't extract compound default literals like objects or Arrays yet, so we don't test those.
|
Hi, I made some tests, and there still be some inconsistencies between the values JSDoc finds from the js code (when using es6 syntax) and values manually documented in doclets. Also there is issue to document "complex" types like objects, arrays, functions,... Sphinx .rstExample .js filehttps://gist.github.com/flozz/0cb94dbe6e79d43ba31c5727684d24fe Tests with simple types/**
* If we let jsdoc extracting the default values (es6 syntax), the
* result is ok for simple types (number, string, boolean and null)
*
* @param {*} a
* @param {number} [b]
* @param {boolean} [c]
* @param {string} [d]
*/
simple_type_implicite(a, b=42, c=false, d="false") {
}
/**
* If we document explicitely values, it does not works as expected:
* If something looks like a boolean or a number, it is "casted", so we
* cannot have a ``"42"`` or a ``"false"`` string
*
* @param {*} a
* @param {number} [b=42]
* @param {boolean} [c=false]
* @param {string} [d=false]
*/
simple_type_explicite(a, b=42, c=false, d="false") {
}
/**
* An other exemple with explicite documentation
*
* @param [a=42]
* @param [b="42"]
* @param [c=false]
* @param [d="false"]
*/
simple_type_explicite2(a, b, c, d) {
}
Tests with more complex types/**
* More complex types are not documented automatically...
*
* @param [obj]
* @param [arr]
* @param [fn]
*/
array_object_function_implicite(obj={}, arr=[], fn=function(){}) {
}
/**
* ... And are "casted" as string when explicitely documented (except for
* objects that does not displayed at all, jsdoc seems to dislike ``{}``
* in @param)
*
* @param [obj={}] Param JSDoc JSON: ``{"name": "obj="}``?
* @param [arr=[]]
* @param [fn=function(){}]
*/
array_object_function_explicite(obj={}, arr=[], fn=function(){}) {
}
Tests with constants/**
* Variable or constants as default value are not automatically
* documented...
*
* @param [a]
*/
constants_implicite(a=SOME_CONST) {
}
/**
* ... and are seen as string if documented explicitely
*
* @param [a=SOME_CONST]
*/
constants_explicite(a=SOME_CONST) {
}
|
|
Sorry for the looooong message...^^' I do not know what is the best thing to do on sphinx-js side:
On JSdoc-side:
Anyway, thank you for asking me to review that PR :) |
|
To summarize (and get it straight in my head)… Using the doclet to document defaults lets you use [], {}, function(), and other complex values. However…
Documenting defaults solely in the JS code is the other option. But this limits you to the types JSDoc can extract: true, 42, "string", and null. And unfortunately, sphinx-js doesn't receive both the doclet and the JS default: we get only the union JSDoc computes. So the best course I see is to use the explicit type declaration, if any, to interpret. If we have a declaration and it is "string", put quotes around the literal text and stitch it into our template. Otherwise, omit the quotes. But this, too, has a problematic corner case: if the type declaration is a disjunction like I also looked at the possibility of using workarounds: for simple_type_explicite and array_object_function_explicite, I'd recommend leaving out the doclet bits that confuse JSDoc. I'm not sure where the |
|
Maybe the simplest thing to do is to
this should avoid any confusion and let the user decide what is displayed |
|
Hmm, I just don't like making people deviate from stock JSDoc syntax; I want sphinx-js to be able to be dropped into existing projects. Let's let it bake a day or two.
|
...which I suspect I need to make the `\"` in my new tests come out right.
* No type that JSDoc extracts correctly from the formal param list needs a type hint: bools, numbers, strs, null.
* Variable references or complex expressions like arrow functions can be documented by including the default in the doclet, as long as you declare a non-string type on it.
* Defaults from doclets for which JSDoc infers the wrong types, like the strings "true" or "42", can be corrected by declaring the correct type in the doclet.
* Param names and default values that contain special ReST chars are now properly escaped.
If you have a tricky disjoint type like `{string|Array}`, specify string first if you want your default to be interpreted as a string.
|
How does this strike you, @flozz? It still needs documentation in the readme, but this way, you can express anything, ES2016-style defaults are always interpreted as correctly as JSDoc allows, and we don't deviate from JSDoc's documented spellings. |
|
For me, it is the right compromise. I tested on my project and it worked just fine :D |
|
And I published 2.5 on PyPI. Cheers! |
JSDoc doesn't extract compound default literals like objects or Arrays yet, so we don't test those.
@flozz Would you mind reviewing this? Thank you!