Since JSDoc seems cerebrally dead...

Michaël Rouges michael.rouges at gmail.com
Sat Oct 17 10:38:21 UTC 2020


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/20201017/a9e662c8/attachment.html>


More information about the es-discuss mailing list