docs: improve tsdoc comments for documentation clarity #148
Conversation
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
| @@ -43,6 +43,7 @@ export class MarketRent { | |||
| averageRentYearly, | |||
| }: MarketRentParams) { | |||
| const averageRentMonthly = averageRentYearly / MONTHS_PER_YEAR; | |||
| // TODO: landToTotalRatio is calculated multiple times in multiple places, can we just do it once? | |||
There was a problem hiding this comment.
Great comment 👍 Worth spinning out into a GH issue maybe?
app/models/Household.ts
Outdated
| @@ -9,6 +9,7 @@ import { ForecastParameters } from "./ForecastParameters"; | |||
| import { socialRentAdjustmentTypes } from "../data/socialRentAdjustmentsRepo"; | |||
| import { Lifetime, LifetimeParams } from "./Lifetime"; | |||
|
|
|||
| /** Assumed number of heads per-house */ | |||
There was a problem hiding this comment.
I had no idea this is what this referred to 💡
Maybe it's worth changing to a more meaningful name?
There was a problem hiding this comment.
Ha that makes sense! Just pushed a new commit--hope that is okay as part of this PR, seemed excessive to make a new one just for that?
| /** The Fairhold class is a generic class | ||
| * (meaning it will calculate a discount regardless if it is given a purchase price or monthly rent). |
There was a problem hiding this comment.
| /** The Fairhold class is a generic class | |
| * (meaning it will calculate a discount regardless if it is given a purchase price or monthly rent). | |
| /** | |
| * The Fairhold class is a generic class | |
| * (meaning it will calculate a discount regardless if it is given a purchase price or monthly rent). |
nit: JSDocs in blocks should have just /** as the first line. It's not broken and it does work, but as it's breaking conventions it feels a bit harder to read / unexpected. This applies multiple times throughout the PR below also.
/** This is the right notation for a single line though 👍 */
There was a problem hiding this comment.
Thanks for letting me know, super useful for future reference! Have now fixed this, I believe :)
What's new in this PR
Updated TSDoc across all modules in the
modelsdirectory. To view docs in browser, runnpm run docs(script is not new).Why
Each time I return to this repo to work on a new feature I find that I've forgotten what a variable name means, why a property is present in a class, or similar--and then I have to re-learn my way around! Hopefully this makes that process easier for all involved.
Feedback, eg if anything is still unclear, is very welcome.