Since JSDoc seems cerebrally dead...

kai zhu kaizhu256 at gmail.com
Wed Oct 14 18:53:16 UTC 2020


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


More information about the es-discuss mailing list