Re: Since JSDoc seems cerebrally dead...
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 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 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 >> 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 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 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 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 >> > html = "\n\n"; >> > Object.entries(local).sort().forEach(function ([ >> > name, obj >> > ]) { >> > if (typeof obj === "function") { >> > obj.toString().replace(( >> >
Re: Since JSDoc seems cerebrally dead...
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 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
> 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 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
>>> 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 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 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
>>> >> > 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 += "function " + name + " " + signature.trim()
>>> + "\n";
>>> >> > html += "\n" + comment + "\n\n";
>>> >> > html += "\n";
>>> >> > });
>>> >> > }
>>> >> > });
>>> >> > html += "\n";
>>> >> > console.log(html);
>>> >> > ```
>>> >> >
>>> >> > output
>>> >> > ```html
>>> >> >
>>> >> >
>>> >> > function foo1 (aa, bb)
>>> >> >
>>> >> > /*
>>> >> > * this function will blah blah blah
>>> >> > */
>>> >> >
>>> >> >
Re: Since JSDoc seems cerebrally dead...
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
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 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
>> 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 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 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
>> >> > 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 += "function " + name + " " + signature.trim()
>> + "\n";
>> >> > html += "\n" + comment + "\n\n";
>> >> > html += "\n";
>> >> > });
>> >> > }
>> >> > });
>> >> > html += "\n";
>> >> > console.log(html);
>> >> > ```
>> >> >
>> >> > output
>> >> > ```html
>> >> >
>> >> >
>> >> > function foo1 (aa, bb)
>> >> >
>> >> > /*
>> >> > * this function will blah blah blah
>> >> > */
>> >> >
>> >> >
>> >> > function foo2 (cc, dd)
>> >> >
>> >> > /*
>> >> > * this function will yada yada yada
>> >> > */
>> >> >
>> >> >
>> >> >
>> >> > ```
>> >> >
>> >> >
>> >> > 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). ;)
>> >> >>
>> >> >>
>>
Re: Since JSDoc seems cerebrally dead...
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 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
> 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 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 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
> >> > 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 += "function " + name + " " + signature.trim() +
> "\n";
> >> > html += "\n" + comment + "\n\n";
> >> > html += "\n";
> >> > });
> >> > }
> >> > });
> >> > html += "\n";
> >> > console.log(html);
> >> > ```
> >> >
> >> > output
> >> > ```html
> >> >
> >> >
> >> > function foo1 (aa, bb)
> >> >
> >> > /*
> >> > * this function will blah blah blah
> >> > */
> >> >
> >> >
> >> > function foo2 (cc, dd)
> >> >
> >> > /*
> >> > * this function will yada yada yada
> >> > */
> >> >
> >> >
> >> >
> >> > ```
> >> >
> >> >
> >> > 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 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 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
Re: Since JSDoc seems cerebrally dead...
That would be interesting indeed. Encouraging documentation is great I think.
#!/JoePea
On Sat, Oct 17, 2020 at 3:38 AM Michaël Rouges 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 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 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
>> > 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 += "function " + name + " " + signature.trim() +
>> > "\n";
>> > html += "\n" + comment + "\n\n";
>> > html += "\n";
>> > });
>> > }
>> > });
>> > html += "\n";
>> > console.log(html);
>> > ```
>> >
>> > output
>> > ```html
>> >
>> >
>> > function foo1 (aa, bb)
>> >
>> > /*
>> > * this function will blah blah blah
>> > */
>> >
>> >
>> > function foo2 (cc, dd)
>> >
>> > /*
>> > * this function will yada yada yada
>> > */
>> >
>> >
>> >
>> > ```
>> >
>> >
>> > On Wed, Oct 14, 2020 at 5:25 AM Michaël Rouges
>> > 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 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 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
>> 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
>> > 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
>> > >
Re: Since JSDoc seems cerebrally dead...
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 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 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
> > 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 += "function " + name + " " + signature.trim() +
> "\n";
> > html += "\n" + comment + "\n\n";
> > html += "\n";
> > });
> > }
> > });
> > html += "\n";
> > console.log(html);
> > ```
> >
> > output
> > ```html
> >
> >
> > function foo1 (aa, bb)
> >
> > /*
> > * this function will blah blah blah
> > */
> >
> >
> > function foo2 (cc, dd)
> >
> > /*
> > * this function will yada yada yada
> > */
> >
> >
> >
> > ```
> >
> >
> > On Wed, Oct 14, 2020 at 5:25 AM Michaël Rouges
> 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 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 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,
Re: Since JSDoc seems cerebrally dead...
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 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
> 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 += "function " + name + " " + signature.trim() +
> "\n";
> html += "\n" + comment + "\n\n";
> html += "\n";
> });
> }
> });
> html += "\n";
> console.log(html);
> ```
>
> output
> ```html
>
>
> function foo1 (aa, bb)
>
> /*
> * this function will blah blah blah
> */
>
>
> function foo2 (cc, dd)
>
> /*
> * this function will yada yada yada
> */
>
>
>
> ```
>
>
> On Wed, Oct 14, 2020 at 5:25 AM Michaël Rouges
> 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 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 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
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
> 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
>
>
Re: Since JSDoc seems cerebrally dead...
> 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 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 += "function "
+ name + " " + signature.trim() + "\n";html += "\n" +
comment + "\n\n";html += "\n";});}});html +=
"\n";console.log(html);*
*```*
*output*
*```html*
*function foo1 (aa, bb)/* * this function will blah
blah blah */function foo2 (cc, dd)/* * this function
will yada yada yada */*
*```*
On Wed, Oct 14, 2020 at 5:25 AM Michaël Rouges
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 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 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
>>> 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
Re: Since JSDoc seems cerebrally dead...
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 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 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 >> 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
Re: Since JSDoc seems cerebrally dead...
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 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 > 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 > 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
Re: Since JSDoc seems cerebrally dead...
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 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 > 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
Re: Re: Since JSDoc seems cerebrally dead...
Sorry, I should be a few more explicit about the needs, I'll try to fix it.
(Sorry If my english isn't perfect, it isn't my native language)
Ihmo, the developers needs a strong/robust/uniform way to describe their
code, using static types comments and how they are using the language
features, enven why they are used for (IDE's autocomplete, doc generation,
AST, subsets compilation, bundling, ...).
Actually, there is a lot of things that requires some **tricks** from
several **external** sources (TS, JSDoc, Clojure, Flow, ...) to
nevertheless cover 100% on our code, like `@async`, the `|` VS `&`, the
`{this}` without classes, the spreading, the `Symbol` references, a lot of
things resolved by the `@template` which doesn't exist in JSDoc, ... where
some of the **missing features** are standardized **since 2011**, it sounds
just crazy!
The real question is: why, when a new language feature is released, the
developers need to wait to describe their uses, depending on an ever
growing collection of external wills to learn?
If I'm asking that to the TC39, it's because:
- they strongly discuss a lot of point of views about every language
features, then they are the most initiated people to define how to describe
them
- that committee must exist as long as the JS exists, then no risk to
have an abandoned spec
- that committee controls the releases flow, it can control the features
comment descriptions to be released at the same time
- ...
Who is better placed to offer the same guarantees?
The community, like actually? I don't think so, it's why we don't have an
unique uptodate solution to rely on it.
But I'm not detracting the community efforts however, it tries to fill the
pending gap until today and can be empowered by a real standardization to
improve/create a lot of amazing tools (IDE's autocomplete, doc generation,
AST, subsets compilation, bundling, ...) on a spec which covers 100% of the
language features usages.
Michaël Rouges - https://github.com/Lcfvs - @Lcfvs
___
es-discuss mailing list
[email protected]
https://mail.mozilla.org/listinfo/es-discuss
Re: Since JSDoc seems cerebrally dead...
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 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
Re: Since JSDoc seems cerebrally dead...
It’s close, but not quite the same, from a cursory read. Thanks for sharing though. To respond to the original post, I don’t think something rigidly formal would work out given how many wildly different opinions are out there - thinking out loud, but perhaps something underlying similar to clojures meta information would enable other approaches. The data contained in jsdoc comments is similar... from a certain perspective. Annotations as first class data would let users come up with solutions without parsing comment bodies, and let that data break out of the walled gardens. I don’t know what the syntax would look like, and still be backward compatible, which is where comments are a clear winner. > On 17. Aug 2020, at 22:09, Jacob Bloom wrote: > > > > This feels like rich territory for a blog post, if someone feels qualified? > > Specifically, just running the typescript tool chain for jsdoc annotations, > > which are excellent for all the reasons mentioned above (comments only, > > vanilla js etc). > > Does this count? > https://devblogs.microsoft.com/typescript/how-to-upgrade-to-typescript-without-anybody-noticing-part-1/ > >> On Mon, Aug 17, 2020 at 2:56 PM Dan Peddle wrote: >> This feels like rich territory for a blog post, if someone feels qualified? >> Specifically, just running the typescript tool chain for jsdoc annotations, >> which are excellent for all the reasons mentioned above (comments only, >> vanilla js etc). >> On 17. Aug 2020, at 19:35, Andrea Giammarchi wrote: >>> >>> Sorry, new link: >>> https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html >>> On Mon, Aug 17, 2020 at 8:34 PM Andrea Giammarchi wrote: TS supports JSDocs already https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html#supported-jsdoc > On Mon, Aug 17, 2020 at 8:31 PM Bergi wrote: > Hi, > > > They don't want to add TS to their stack. > > Then what else would they want to add to their stack? Notice one doesn't > necessarily need the TypeScript Compiler to add TypeScript- or Flow-like > type annotations and remove them in a build step - Babel for example > could do that just fine as well. > Or are you asking for a jsdoc-like thing that lives in comments, where > the code can be run without a compilation step? > > kind regards, > Bergi > ___ > 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
Re: Since JSDoc seems cerebrally dead...
> This feels like rich territory for a blog post, if someone feels qualified? Specifically, just running the typescript tool chain for jsdoc annotations, which are excellent for all the reasons mentioned above (comments only, vanilla js etc). Does this count? https://devblogs.microsoft.com/typescript/how-to-upgrade-to-typescript-without-anybody-noticing-part-1/ On Mon, Aug 17, 2020 at 2:56 PM Dan Peddle wrote: > This feels like rich territory for a blog post, if someone feels > qualified? Specifically, just running the typescript tool chain for jsdoc > annotations, which are excellent for all the reasons mentioned above > (comments only, vanilla js etc). > > On 17. Aug 2020, at 19:35, Andrea Giammarchi > wrote: > > > Sorry, new link: > https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html > > On Mon, Aug 17, 2020 at 8:34 PM Andrea Giammarchi < > [email protected]> wrote: > >> TS supports JSDocs already >> >> https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html#supported-jsdoc >> >> On Mon, Aug 17, 2020 at 8:31 PM Bergi wrote: >> >>> Hi, >>> >>> > They don't want to add TS to their stack. >>> >>> Then what else would they want to add to their stack? Notice one doesn't >>> necessarily need the TypeScript Compiler to add TypeScript- or Flow-like >>> type annotations and remove them in a build step - Babel for example >>> could do that just fine as well. >>> Or are you asking for a jsdoc-like thing that lives in comments, where >>> the code can be run without a compilation step? >>> >>> kind regards, >>> Bergi >>> ___ >>> 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
Re: Since JSDoc seems cerebrally dead...
This feels like rich territory for a blog post, if someone feels qualified? Specifically, just running the typescript tool chain for jsdoc annotations, which are excellent for all the reasons mentioned above (comments only, vanilla js etc). > On 17. Aug 2020, at 19:35, Andrea Giammarchi > wrote: > > > Sorry, new link: > https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html > >> On Mon, Aug 17, 2020 at 8:34 PM Andrea Giammarchi >> wrote: >> TS supports JSDocs already >> https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html#supported-jsdoc >> >>> On Mon, Aug 17, 2020 at 8:31 PM Bergi wrote: >>> Hi, >>> >>> > They don't want to add TS to their stack. >>> >>> Then what else would they want to add to their stack? Notice one doesn't >>> necessarily need the TypeScript Compiler to add TypeScript- or Flow-like >>> type annotations and remove them in a build step - Babel for example >>> could do that just fine as well. >>> Or are you asking for a jsdoc-like thing that lives in comments, where >>> the code can be run without a compilation step? >>> >>> kind regards, >>> Bergi >>> ___ >>> 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
Re: Since JSDoc seems cerebrally dead...
Sorry, new link: https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html On Mon, Aug 17, 2020 at 8:34 PM Andrea Giammarchi < [email protected]> wrote: > TS supports JSDocs already > > https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html#supported-jsdoc > > On Mon, Aug 17, 2020 at 8:31 PM Bergi wrote: > >> Hi, >> >> > They don't want to add TS to their stack. >> >> Then what else would they want to add to their stack? Notice one doesn't >> necessarily need the TypeScript Compiler to add TypeScript- or Flow-like >> type annotations and remove them in a build step - Babel for example >> could do that just fine as well. >> Or are you asking for a jsdoc-like thing that lives in comments, where >> the code can be run without a compilation step? >> >> kind regards, >> Bergi >> ___ >> 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
Re: Since JSDoc seems cerebrally dead...
TS supports JSDocs already https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html#supported-jsdoc On Mon, Aug 17, 2020 at 8:31 PM Bergi wrote: > Hi, > > > They don't want to add TS to their stack. > > Then what else would they want to add to their stack? Notice one doesn't > necessarily need the TypeScript Compiler to add TypeScript- or Flow-like > type annotations and remove them in a build step - Babel for example > could do that just fine as well. > Or are you asking for a jsdoc-like thing that lives in comments, where > the code can be run without a compilation step? > > kind regards, > Bergi > ___ > 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
Re: Since JSDoc seems cerebrally dead...
Hi, > They don't want to add TS to their stack. Then what else would they want to add to their stack? Notice one doesn't necessarily need the TypeScript Compiler to add TypeScript- or Flow-like type annotations and remove them in a build step - Babel for example could do that just fine as well. Or are you asking for a jsdoc-like thing that lives in comments, where the code can be run without a compilation step? kind regards, Bergi ___ es-discuss mailing list [email protected] https://mail.mozilla.org/listinfo/es-discuss
