Since JSDoc seems cerebrally dead...

Jacob Bloom mr.jacob.bloom at gmail.com
Wed Nov 11 22:05:24 UTC 2020


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/20201111/d350cf2d/attachment-0001.html>


More information about the es-discuss mailing list