Since JSDoc seems cerebrally dead...

Michaël Rouges michael.rouges at gmail.com
Thu Nov 12 08:51:39 UTC 2020


Yeah, that's the problem, no totally robust solution, often resorting to
`any`, often the need to take some tricks from several sources, etc.

That's why I'm asking about a truly standard solution, thought during the
TC features proposal.

Imho, if a feature can't be fully described, it must be rethought until it
can.

Michaël Rouges - https://github.com/Lcfvs - @Lcfvs


Le mer. 11 nov. 2020 à 23:05, Jacob Bloom <mr.jacob.bloom at gmail.com> a
écrit :

> This SO answer provides a typing for Object.assign that appears to
> basically do the right thing: https://stackoverflow.com/a/51603499 -- but
> none of the above libraries use this kind of solution, which leads me to
> think it might not be totally robust
>
> On Wed, Nov 11, 2020 at 1:27 PM Jordan Harband <ljharb at gmail.com> wrote:
>
>> Of course there's a way - it's just that TS's built-in types don't
>> consistently go the extra mile, and often resort to `any`. See
>> https://github.com/DefinitelyTyped/DefinitelyTyped/blob/5344bfc80508c53a23dae37b860fb0c905ff7b24/types/object-assign/index.d.ts,
>> or
>> https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/lodash/common/object.d.ts#L32-L52,
>> for two examples of `Object.assign`, as an example.
>>
>> On Wed, Nov 11, 2020 at 8:51 AM Michaël Rouges <michael.rouges at gmail.com>
>> wrote:
>>
>>> Some other cases, not covered, even in JSDoc nor TS
>>>
>>> There is no way to describe the result, to the IDE's intellisense, for
>>> those ES5/ES2015 features:
>>> `Object.create(prototype, descriptors)`
>>> https://github.com/microsoft/TypeScript/blob/master/lib/lib.es5.d.ts#L192
>>> `Object.assign(obj, ...mixins)`
>>> https://github.com/microsoft/TypeScript/blob/master/lib/lib.es2015.core.d.ts#L313
>>>
>>> I really love JS, but if there is no way to help the IDE to understand
>>> complex things, it's like to code with a Notepad.exe
>>>
>>> Any TC feelings about that, please?
>>>
>>> Michaël Rouges - https://github.com/Lcfvs - @Lcfvs
>>>
>>>
>>> Le dim. 18 oct. 2020 à 05:27, #!/JoePea <joe at trusktr.io> a écrit :
>>>
>>>> That would be interesting indeed. Encouraging documentation is great I
>>>> think.
>>>> #!/JoePea
>>>>
>>>> On Sat, Oct 17, 2020 at 3:38 AM Michaël Rouges <
>>>> michael.rouges at gmail.com> wrote:
>>>> >
>>>> > Yeah, I prefer the JSDoc solution too for the same reasons... but
>>>> JSDoc is really slow to evolve,
>>>> > always several years behind the standard, a lot of solutions to
>>>> describe our code are more relevant
>>>> > to **tricks**, generally found on the JSDoc issues, than something
>>>> formal.
>>>> >
>>>> > The coverage isn't the same... really, I'm dreaming about a standard
>>>> annotation for each ES feature,
>>>> > covering all the usages. **when that feature is released**.
>>>> >
>>>> >
>>>> > Michaël Rouges - https://github.com/Lcfvs - @Lcfvs
>>>> >
>>>> >
>>>> > Le sam. 17 oct. 2020 à 03:29, #!/JoePea <joe at trusktr.io> a écrit :
>>>> >>
>>>> >> Would official syntax be worth it (JSDoc being officially
>>>> standardized)?
>>>> >>
>>>> >> Maybe it's a matter of time: Perhaps now that JSDoc is useful for
>>>> type
>>>> >> checking (thanks to TypeScript and its ability to type check plain
>>>> >> JavaScript that is annotated with JSDoc) it may be closer to reality.
>>>> >>
>>>> >> I prefer JSDoc type annotation in plain .js files over writing .ts
>>>> >> files, because it means I can write type-checked code that has great
>>>> >> intellisense in modern editors like VS Code, without needing any
>>>> build
>>>> >> steps and with end users being able to consume those source files
>>>> >> directly in any way they want (possibly also without build tools).
>>>> >> However, JSDoc can not currently do everything that regular
>>>> TypeScript
>>>> >> syntax can do (there's some open issues regarding that in the
>>>> >> TypeScript repo).
>>>> >>
>>>> >> #!/JoePea
>>>> >>
>>>> >> On Wed, Oct 14, 2020 at 11:53 AM kai zhu <kaizhu256 at gmail.com>
>>>> wrote:
>>>> >> >
>>>> >> > > Sorry but my question isn't about providing a tool to generate
>>>> our documentations but to have a standard syntax to describe our code
>>>> (signatures). ;)
>>>> >> >
>>>> >> > not standard-practice, but my style is to have documentation of
>>>> functions inside the function (rather than above it).
>>>> >> > simplifies doc-generation by calling function's `.toString()`
>>>> (rather than having to parse the parse the entire script):
>>>> >> >
>>>> >> > ```js
>>>> >> > let html;
>>>> >> > let local;
>>>> >> > local = {};
>>>> >> > local.foo1 = function (aa, bb) {
>>>> >> > /*
>>>> >> >  * this function will blah blah blah
>>>> >> >  */
>>>> >> >     return aa + bb;
>>>> >> > };
>>>> >> > local.foo2 = function (cc, dd) {
>>>> >> > /*
>>>> >> >  * this function will yada yada yada
>>>> >> >  */
>>>> >> >     return cc + dd;
>>>> >> > };
>>>> >> >
>>>> >> > // auto-generate doc for functions in namespace <local>
>>>> >> > html = "<html>\n\n";
>>>> >> > Object.entries(local).sort().forEach(function ([
>>>> >> >     name, obj
>>>> >> > ]) {
>>>> >> >     if (typeof obj === "function") {
>>>> >> >         obj.toString().replace((
>>>> >> >
>>>>  /function\b.*?(\([\S\s]*?\))\s*?\{\n?(\s*?\/\*[\S\s]*?\*\/)/
>>>> >> >         ), function (ignore, signature, comment) {
>>>> >> >             html += "<h1>function " + name + " " +
>>>> signature.trim() + "</h1>\n";
>>>> >> >             html += "<pre>\n" + comment + "\n</pre>\n";
>>>> >> >             html += "\n";
>>>> >> >         });
>>>> >> >     }
>>>> >> > });
>>>> >> > html += "</html>\n";
>>>> >> > console.log(html);
>>>> >> > ```
>>>> >> >
>>>> >> > output
>>>> >> > ```html
>>>> >> > <html>
>>>> >> >
>>>> >> > <h1>function foo1 (aa, bb)</h1>
>>>> >> > <pre>
>>>> >> > /*
>>>> >> >  * this function will blah blah blah
>>>> >> >  */
>>>> >> > </pre>
>>>> >> >
>>>> >> > <h1>function foo2 (cc, dd)</h1>
>>>> >> > <pre>
>>>> >> > /*
>>>> >> >  * this function will yada yada yada
>>>> >> >  */
>>>> >> > </pre>
>>>> >> >
>>>> >> > </html>
>>>> >> > ```
>>>> >> >
>>>> >> >
>>>> >> > On Wed, Oct 14, 2020 at 5:25 AM Michaël Rouges <
>>>> michael.rouges at gmail.com> wrote:
>>>> >> >>
>>>> >> >> Sorry but my question isn't about providing a tool to generate
>>>> our documentations but to have a standard syntax to describe our code
>>>> (signatures). ;)
>>>> >> >>
>>>> >> >>
>>>> >> >> Michaël Rouges - https://github.com/Lcfvs - @Lcfvs
>>>> >> >>
>>>> >> >>
>>>> >> >> Le mar. 13 oct. 2020 à 01:29, Jordan Harband <ljharb at gmail.com>
>>>> a écrit :
>>>> >> >>>
>>>> >> >>> Hopefully (imo) people are hand-writing more docs now, rather
>>>> than relying on autogenerated prose.
>>>> >> >>>
>>>> >> >>> On Mon, Oct 12, 2020 at 1:23 PM #!/JoePea <joe at trusktr.io>
>>>> wrote:
>>>> >> >>>>
>>>> >> >>>> Why not? People are generating less docs now? That doesn't
>>>> sound good!
>>>> >> >>>>
>>>> >> >>>> #!/JoePea
>>>> >> >>>>
>>>> >> >>>> On Mon, Aug 17, 2020 at 4:15 PM Isiah Meadows <
>>>> contact at isiahmeadows.com> wrote:
>>>> >> >>>> >
>>>> >> >>>> > JSDoc is not dead (far from it), people just don't frequently
>>>> use
>>>> >> >>>> > automated docs generation tooling in the JS community. Most
>>>> the actual
>>>> >> >>>> > use JSDoc provides nowadays is editor autocomplete hints and
>>>> >> >>>> > integrating with TypeScript (in cases where changing the
>>>> extension
>>>> >> >>>> > isn't possible for whatever reason), so while it's still
>>>> useful, it's
>>>> >> >>>> > just not used in the same places it was used previously.
>>>> >> >>>> >
>>>> >> >>>> > -----
>>>> >> >>>> >
>>>> >> >>>> > Isiah Meadows
>>>> >> >>>> > contact at isiahmeadows.com
>>>> >> >>>> > www.isiahmeadows.com
>>>> >> >>>> >
>>>> >> >>>> > On Sun, Aug 16, 2020 at 6:39 PM Michaël Rouges <
>>>> michael.rouges at gmail.com> wrote:
>>>> >> >>>> > >
>>>> >> >>>> > > Hi all,
>>>> >> >>>> > >
>>>> >> >>>> > > Since JSDoc seems cerebrally dead, why the TC39 doesn't
>>>> make a real documentation standard, evolving with the langage?
>>>> >> >>>> > >
>>>> >> >>>> > > Actually, a part of  the JS community are exiling to TS to
>>>> type anything and the rest are just despited by the very outdated version
>>>> of JSDoc but don't want to add TS to their stack.
>>>> >> >>>> > >
>>>> >> >>>> > > IMHO, it's really urgent to have something formal to solve
>>>> that missing point of my favorite language.
>>>> >> >>>> > >
>>>> >> >>>> > > What would it take to make this dream come true, please?
>>>> >> >>>> > >
>>>> >> >>>> > >
>>>> >> >>>> > > Michaël Rouges - https://github.com/Lcfvs - @Lcfvs
>>>> >> >>>> > > _______________________________________________
>>>> >> >>>> > > es-discuss mailing list
>>>> >> >>>> > > es-discuss at mozilla.org
>>>> >> >>>> > > https://mail.mozilla.org/listinfo/es-discuss
>>>> >> >>>> > _______________________________________________
>>>> >> >>>> > es-discuss mailing list
>>>> >> >>>> > es-discuss at mozilla.org
>>>> >> >>>> > https://mail.mozilla.org/listinfo/es-discuss
>>>> >> >>>> _______________________________________________
>>>> >> >>>> es-discuss mailing list
>>>> >> >>>> es-discuss at mozilla.org
>>>> >> >>>> https://mail.mozilla.org/listinfo/es-discuss
>>>> >> >>
>>>> >> >> _______________________________________________
>>>> >> >> es-discuss mailing list
>>>> >> >> es-discuss at mozilla.org
>>>> >> >> https://mail.mozilla.org/listinfo/es-discuss
>>>> >> >
>>>> >> > _______________________________________________
>>>> >> > es-discuss mailing list
>>>> >> > es-discuss at mozilla.org
>>>> >> > https://mail.mozilla.org/listinfo/es-discuss
>>>>
>>> _______________________________________________
>>> es-discuss mailing list
>>> es-discuss at mozilla.org
>>> https://mail.mozilla.org/listinfo/es-discuss
>>>
>> _______________________________________________
>> es-discuss mailing list
>> es-discuss at mozilla.org
>> https://mail.mozilla.org/listinfo/es-discuss
>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.mozilla.org/pipermail/es-discuss/attachments/20201112/92a97db4/attachment-0001.html>


More information about the es-discuss mailing list