That would be interesting indeed. Encouraging documentation is great I think. #!/JoePea
On Sat, Oct 17, 2020 at 3:38 AM Michaël Rouges <[email protected]> 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 <[email protected]> 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 <[email protected]> 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 <[email protected]> >> > 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 <[email protected]> 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 <[email protected]> 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 >> >>>> <[email protected]> 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 >> >>>> > [email protected] >> >>>> > www.isiahmeadows.com >> >>>> > >> >>>> > On Sun, Aug 16, 2020 at 6:39 PM Michaël Rouges >> >>>> > <[email protected]> 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 >> >>>> > > [email protected] >> >>>> > > https://mail.mozilla.org/listinfo/es-discuss >> >>>> > _______________________________________________ >> >>>> > es-discuss mailing list >> >>>> > [email protected] >> >>>> > https://mail.mozilla.org/listinfo/es-discuss >> >>>> _______________________________________________ >> >>>> es-discuss mailing list >> >>>> [email protected] >> >>>> https://mail.mozilla.org/listinfo/es-discuss >> >> >> >> _______________________________________________ >> >> es-discuss mailing list >> >> [email protected] >> >> https://mail.mozilla.org/listinfo/es-discuss >> > >> > _______________________________________________ >> > es-discuss mailing list >> > [email protected] >> > https://mail.mozilla.org/listinfo/es-discuss _______________________________________________ es-discuss mailing list [email protected] https://mail.mozilla.org/listinfo/es-discuss
