This SO answer provides a typing for Object.assign that appears to basically do the right thing: https://stackoverflow.com/a/51603499 -- but none of the above libraries use this kind of solution, which leads me to think it might not be totally robust
On Wed, Nov 11, 2020 at 1:27 PM Jordan Harband <[email protected]> wrote: > 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 >
_______________________________________________ es-discuss mailing list [email protected] https://mail.mozilla.org/listinfo/es-discuss
