Since JSDoc seems cerebrally dead...

Jordan Harband ljharb at gmail.com
Wed Nov 11 20:26:16 UTC 2020


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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.mozilla.org/pipermail/es-discuss/attachments/20201111/88f66950/attachment-0001.html>


More information about the es-discuss mailing list