chrisdothtml
commented
2 years ago +1
Personally I do like using the JSDoc syntax in smaller projects, but have found it falls short for more complex scenarios (e.g. overrides, interfaces). I don't think that makes JSDoc a hopeless cause though; I think supplementing it with flow-like comment support would be better and avoid the permanence of new JS syntax. For example:
Existing syntax still works for simple stuff
/**
* @param {number} p1
* @param {number} p2
* @return {number}
*/
function add(p1, p2) {
return p1 + p2;
}But also works with more complex types by supporting full typescript syntax in block comments
/*::
interface Person {
name: string;
age: number;
}
*/
/**
* @param {Person} person
* @return {void}
*/
function greetPerson(person) {
console.log(`Hello, ${person.name}!`);
}And can be circumvented entirely if needed
/*::
interface Person {
name: string;
age: number;
}
type GreetFunction = (person: Person) => void;
*/
/**
* @type {GreetFunction}
*/
function greetPerson(person) {
console.log(`Hello, ${person.name}!`);
}
bakkot
edmundmunday
ljharb
nweldev
giltayar
wparad
ptomato
Jack-Works
lillallol
The obvious alternative to this proposal is to just use the existing comment syntax for types. The readme's counterargument is that JSDoc comments are verbose and missing some things you'd want to do in typescript. This is true, but not obviously relevant, since JSDoc is not the only syntax possible. As an existence proof, Flow's type comments are quite concise and support (I believe) all of Flow.
So why the focus on JSDoc? The readme currently makes it sound like JSDoc is the only imaginable way to use the existing comment syntax, and concludes that the (true) fact that JSDoc is verbose and unergonomic is therefore a reason that the existing comment syntax is inadequate, but that seems to be a deficiency in JSDoc in particular rather than comments in general.