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 <j...@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 <kaizhu...@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.rou...@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 <ljh...@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 <j...@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 < > cont...@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 > >>>> > cont...@isiahmeadows.com > >>>> > www.isiahmeadows.com > >>>> > > >>>> > On Sun, Aug 16, 2020 at 6:39 PM Michaël Rouges < > michael.rou...@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@mozilla.org > >>>> > > https://mail.mozilla.org/listinfo/es-discuss > >>>> > _______________________________________________ > >>>> > es-discuss mailing list > >>>> > es-discuss@mozilla.org > >>>> > https://mail.mozilla.org/listinfo/es-discuss > >>>> _______________________________________________ > >>>> es-discuss mailing list > >>>> es-discuss@mozilla.org > >>>> https://mail.mozilla.org/listinfo/es-discuss > >> > >> _______________________________________________ > >> es-discuss mailing list > >> es-discuss@mozilla.org > >> https://mail.mozilla.org/listinfo/es-discuss > > > > _______________________________________________ > > es-discuss mailing list > > es-discuss@mozilla.org > > https://mail.mozilla.org/listinfo/es-discuss >
_______________________________________________ es-discuss mailing list es-discuss@mozilla.org https://mail.mozilla.org/listinfo/es-discuss
