<div dir="ltr"><div>Some other cases, not covered, even in JSDoc nor TS</div><div><br></div><div>There is no way to describe the result, to the IDE's intellisense, for those ES5/ES2015 features:</div>`<code class="gmail-inline">Object.create(prototype, descriptors)</code>` <a class="gmail-anchor-3Z-8Bb gmail-anchorUnderlineOnHover-2ESHQB" title="https://github.com/microsoft/TypeScript/blob/master/lib/lib.es5.d.ts#L192" href="https://github.com/microsoft/TypeScript/blob/master/lib/lib.es5.d.ts#L192" rel="noreferrer noopener" target="_blank" tabindex="0">https://github.com/microsoft/TypeScript/blob/master/lib/lib.es5.d.ts#L192</a> <br><div><code class="gmail-inline">`Object.assign(obj, ...mixins)` </code><a class="gmail-anchor-3Z-8Bb gmail-anchorUnderlineOnHover-2ESHQB" title="https://github.com/microsoft/TypeScript/blob/master/lib/lib.es2015.core.d.ts#L313" href="https://github.com/microsoft/TypeScript/blob/master/lib/lib.es2015.core.d.ts#L313" rel="noreferrer noopener" target="_blank" tabindex="0">https://github.com/microsoft/TypeScript/blob/master/lib/lib.es2015.core.d.ts#L313</a></div><div><br></div><div>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</div><div><br></div><div>Any TC feelings about that, please?<br>

</div><div><br></div><div></div><div><div><div dir="ltr" class="gmail_signature" data-smartmail="gmail_signature"><div dir="ltr">Michaël Rouges - <a href="https://github.com/Lcfvs" target="_blank">https://github.com/Lcfvs</a> - @Lcfvs<br></div></div></div><br></div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">Le dim. 18 oct. 2020 à 05:27, #!/JoePea <<a href="mailto:joe@trusktr.io">joe@trusktr.io</a>> a écrit :<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">That would be interesting indeed. Encouraging documentation is great I think.<br>
#!/JoePea<br>
<br>
On Sat, Oct 17, 2020 at 3:38 AM Michaël Rouges <<a href="mailto:michael.rouges@gmail.com" target="_blank">michael.rouges@gmail.com</a>> wrote:<br>
><br>
> Yeah, I prefer the JSDoc solution too for the same reasons... but JSDoc is really slow to evolve,<br>
> always several years behind the standard, a lot of solutions to describe our code are more relevant<br>
> to **tricks**, generally found on the JSDoc issues, than something formal.<br>
><br>
> The coverage isn't the same... really, I'm dreaming about a standard annotation for each ES feature,<br>
> covering all the usages. **when that feature is released**.<br>
><br>
><br>
> Michaël Rouges - <a href="https://github.com/Lcfvs" rel="noreferrer" target="_blank">https://github.com/Lcfvs</a> - @Lcfvs<br>
><br>
><br>
> Le sam. 17 oct. 2020 à 03:29, #!/JoePea <<a href="mailto:joe@trusktr.io" target="_blank">joe@trusktr.io</a>> a écrit :<br>
>><br>
>> Would official syntax be worth it (JSDoc being officially standardized)?<br>
>><br>
>> Maybe it's a matter of time: Perhaps now that JSDoc is useful for type<br>
>> checking (thanks to TypeScript and its ability to type check plain<br>
>> JavaScript that is annotated with JSDoc) it may be closer to reality.<br>
>><br>
>> I prefer JSDoc type annotation in plain .js files over writing .ts<br>
>> files, because it means I can write type-checked code that has great<br>
>> intellisense in modern editors like VS Code, without needing any build<br>
>> steps and with end users being able to consume those source files<br>
>> directly in any way they want (possibly also without build tools).<br>
>> However, JSDoc can not currently do everything that regular TypeScript<br>
>> syntax can do (there's some open issues regarding that in the<br>
>> TypeScript repo).<br>
>><br>
>> #!/JoePea<br>
>><br>
>> On Wed, Oct 14, 2020 at 11:53 AM kai zhu <<a href="mailto:kaizhu256@gmail.com" target="_blank">kaizhu256@gmail.com</a>> wrote:<br>
>> ><br>
>> > > 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). ;)<br>
>> ><br>
>> > not standard-practice, but my style is to have documentation of functions inside the function (rather than above it).<br>
>> > simplifies doc-generation by calling function's `.toString()` (rather than having to parse the parse the entire script):<br>
>> ><br>
>> > ```js<br>
>> > let html;<br>
>> > let local;<br>
>> > local = {};<br>
>> > local.foo1 = function (aa, bb) {<br>
>> > /*<br>
>> >  * this function will blah blah blah<br>
>> >  */<br>
>> >     return aa + bb;<br>
>> > };<br>
>> > local.foo2 = function (cc, dd) {<br>
>> > /*<br>
>> >  * this function will yada yada yada<br>
>> >  */<br>
>> >     return cc + dd;<br>
>> > };<br>
>> ><br>
>> > // auto-generate doc for functions in namespace <local><br>
>> > html = "<html>\n\n";<br>
>> > Object.entries(local).sort().forEach(function ([<br>
>> >     name, obj<br>
>> > ]) {<br>
>> >     if (typeof obj === "function") {<br>
>> >         obj.toString().replace((<br>
>> >             /function\b.*?(\([\S\s]*?\))\s*?\{\n?(\s*?\/\*[\S\s]*?\*\/)/<br>
>> >         ), function (ignore, signature, comment) {<br>
>> >             html += "<h1>function " + name + " " + signature.trim() + "</h1>\n";<br>
>> >             html += "<pre>\n" + comment + "\n</pre>\n";<br>
>> >             html += "\n";<br>
>> >         });<br>
>> >     }<br>
>> > });<br>
>> > html += "</html>\n";<br>
>> > console.log(html);<br>
>> > ```<br>
>> ><br>
>> > output<br>
>> > ```html<br>
>> > <html><br>
>> ><br>
>> > <h1>function foo1 (aa, bb)</h1><br>
>> > <pre><br>
>> > /*<br>
>> >  * this function will blah blah blah<br>
>> >  */<br>
>> > </pre><br>
>> ><br>
>> > <h1>function foo2 (cc, dd)</h1><br>
>> > <pre><br>
>> > /*<br>
>> >  * this function will yada yada yada<br>
>> >  */<br>
>> > </pre><br>
>> ><br>
>> > </html><br>
>> > ```<br>
>> ><br>
>> ><br>
>> > On Wed, Oct 14, 2020 at 5:25 AM Michaël Rouges <<a href="mailto:michael.rouges@gmail.com" target="_blank">michael.rouges@gmail.com</a>> wrote:<br>
>> >><br>
>> >> 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). ;)<br>
>> >><br>
>> >><br>
>> >> Michaël Rouges - <a href="https://github.com/Lcfvs" rel="noreferrer" target="_blank">https://github.com/Lcfvs</a> - @Lcfvs<br>
>> >><br>
>> >><br>
>> >> Le mar. 13 oct. 2020 à 01:29, Jordan Harband <<a href="mailto:ljharb@gmail.com" target="_blank">ljharb@gmail.com</a>> a écrit :<br>
>> >>><br>
>> >>> Hopefully (imo) people are hand-writing more docs now, rather than relying on autogenerated prose.<br>
>> >>><br>
>> >>> On Mon, Oct 12, 2020 at 1:23 PM #!/JoePea <<a href="mailto:joe@trusktr.io" target="_blank">joe@trusktr.io</a>> wrote:<br>
>> >>>><br>
>> >>>> Why not? People are generating less docs now? That doesn't sound good!<br>
>> >>>><br>
>> >>>> #!/JoePea<br>
>> >>>><br>
>> >>>> On Mon, Aug 17, 2020 at 4:15 PM Isiah Meadows <<a href="mailto:contact@isiahmeadows.com" target="_blank">contact@isiahmeadows.com</a>> wrote:<br>
>> >>>> ><br>
>> >>>> > JSDoc is not dead (far from it), people just don't frequently use<br>
>> >>>> > automated docs generation tooling in the JS community. Most the actual<br>
>> >>>> > use JSDoc provides nowadays is editor autocomplete hints and<br>
>> >>>> > integrating with TypeScript (in cases where changing the extension<br>
>> >>>> > isn't possible for whatever reason), so while it's still useful, it's<br>
>> >>>> > just not used in the same places it was used previously.<br>
>> >>>> ><br>
>> >>>> > -----<br>
>> >>>> ><br>
>> >>>> > Isiah Meadows<br>
>> >>>> > <a href="mailto:contact@isiahmeadows.com" target="_blank">contact@isiahmeadows.com</a><br>
>> >>>> > <a href="http://www.isiahmeadows.com" rel="noreferrer" target="_blank">www.isiahmeadows.com</a><br>
>> >>>> ><br>
>> >>>> > On Sun, Aug 16, 2020 at 6:39 PM Michaël Rouges <<a href="mailto:michael.rouges@gmail.com" target="_blank">michael.rouges@gmail.com</a>> wrote:<br>
>> >>>> > ><br>
>> >>>> > > Hi all,<br>
>> >>>> > ><br>
>> >>>> > > Since JSDoc seems cerebrally dead, why the TC39 doesn't make a real documentation standard, evolving with the langage?<br>
>> >>>> > ><br>
>> >>>> > > 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.<br>
>> >>>> > ><br>
>> >>>> > > IMHO, it's really urgent to have something formal to solve that missing point of my favorite language.<br>
>> >>>> > ><br>
>> >>>> > > What would it take to make this dream come true, please?<br>
>> >>>> > ><br>
>> >>>> > ><br>
>> >>>> > > Michaël Rouges - <a href="https://github.com/Lcfvs" rel="noreferrer" target="_blank">https://github.com/Lcfvs</a> - @Lcfvs<br>
>> >>>> > > _______________________________________________<br>
>> >>>> > > es-discuss mailing list<br>
>> >>>> > > <a href="mailto:es-discuss@mozilla.org" target="_blank">es-discuss@mozilla.org</a><br>
>> >>>> > > <a href="https://mail.mozilla.org/listinfo/es-discuss" rel="noreferrer" target="_blank">https://mail.mozilla.org/listinfo/es-discuss</a><br>
>> >>>> > _______________________________________________<br>
>> >>>> > es-discuss mailing list<br>
>> >>>> > <a href="mailto:es-discuss@mozilla.org" target="_blank">es-discuss@mozilla.org</a><br>
>> >>>> > <a href="https://mail.mozilla.org/listinfo/es-discuss" rel="noreferrer" target="_blank">https://mail.mozilla.org/listinfo/es-discuss</a><br>
>> >>>> _______________________________________________<br>
>> >>>> es-discuss mailing list<br>
>> >>>> <a href="mailto:es-discuss@mozilla.org" target="_blank">es-discuss@mozilla.org</a><br>
>> >>>> <a href="https://mail.mozilla.org/listinfo/es-discuss" rel="noreferrer" target="_blank">https://mail.mozilla.org/listinfo/es-discuss</a><br>
>> >><br>
>> >> _______________________________________________<br>
>> >> es-discuss mailing list<br>
>> >> <a href="mailto:es-discuss@mozilla.org" target="_blank">es-discuss@mozilla.org</a><br>
>> >> <a href="https://mail.mozilla.org/listinfo/es-discuss" rel="noreferrer" target="_blank">https://mail.mozilla.org/listinfo/es-discuss</a><br>
>> ><br>
>> > _______________________________________________<br>
>> > es-discuss mailing list<br>
>> > <a href="mailto:es-discuss@mozilla.org" target="_blank">es-discuss@mozilla.org</a><br>
>> > <a href="https://mail.mozilla.org/listinfo/es-discuss" rel="noreferrer" target="_blank">https://mail.mozilla.org/listinfo/es-discuss</a><br>
</blockquote></div>