Since JSDoc seems cerebrally dead...

Michaël Rouges michael.rouges at gmail.com
Wed Nov 11 16:51:07 UTC 2020


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


More information about the es-discuss mailing list