Of course there's a way - it's just that TS's built-in types don't consistently go the extra mile, and often resort to `any`. See https://github.com/DefinitelyTyped/DefinitelyTyped/blob/5344bfc80508c53a23dae37b860fb0c905ff7b24/types/object-assign/index.d.ts, or https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/lodash/common/object.d.ts#L32-L52, for two examples of `Object.assign`, as an example.
On Wed, Nov 11, 2020 at 8:51 AM Michaël Rouges <[email protected]> wrote: > Some other cases, not covered, even in JSDoc nor TS > > There is no way to describe the result, to the IDE's intellisense, for > those ES5/ES2015 features: > `Object.create(prototype, descriptors)` > https://github.com/microsoft/TypeScript/blob/master/lib/lib.es5.d.ts#L192 > `Object.assign(obj, ...mixins)` > https://github.com/microsoft/TypeScript/blob/master/lib/lib.es2015.core.d.ts#L313 > > 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 > > Any TC feelings about that, please? > > Michaël Rouges - https://github.com/Lcfvs - @Lcfvs > > > Le dim. 18 oct. 2020 à 05:27, #!/JoePea <[email protected]> a écrit : > >> 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 >
_______________________________________________ es-discuss mailing list [email protected] https://mail.mozilla.org/listinfo/es-discuss
