Yeah, that's the problem, no totally robust solution, often resorting to `any`, often the need to take some tricks from several sources, etc.
That's why I'm asking about a truly standard solution, thought during the TC features proposal. Imho, if a feature can't be fully described, it must be rethought until it can. Michaël Rouges - https://github.com/Lcfvs - @Lcfvs Le mer. 11 nov. 2020 à 23:05, Jacob Bloom <mr.jacob.bl...@gmail.com> a écrit : > 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 <ljh...@gmail.com> 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 <michael.rou...@gmail.com> >> 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 <j...@trusktr.io> 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 < >>>> michael.rou...@gmail.com> 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 <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 >>> >> _______________________________________________ >> 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
