I was adding TSDoc to a type guard function and found out that using @returns might not be the most appropriate way to document a type guard.
/**
* Type guard to tell if a pet is a fish or a bird.
*
* @param pet - A pet that is either a fish or a bird.
*
* @returns True if the pet can swim, otherwise false.
*/
function isFish(pet: Fish | Bird): pet is Fish {
return (pet as Fish).swim !== undefined;
}
Are there other ways like @casts that might be more meaningful than documenting what the boolean value does on the function?
/**
* Type guard to tell if a pet is a fish or a bird.
*
* @param pet - A pet that is either a fish or a bird.
*
* @casts The pet is a `Fish` if it can `swim`, otherwise it is a `Bird`.
*/
function isFish2(pet: Fish | Bird): pet is Fish {
return (pet as Fish).swim !== undefined;
}