chore: @ignore a lot of generated code to cleanup typedoc output #426
Conversation
| @@ -43,12 +43,15 @@ import { | |||
| tagConfig, | |||
| } from "./entities"; | |||
|
|
|||
| /** @ignore */ | |||
There was a problem hiding this comment.
RE: The @ignore's in this file. I was on the fence about whether I should ignore everything in this file (which is what has been done) vs. use the typedoc --exclude option to skip this file.
I decided to go with the ignore all the things route, since it seemed likely that would be the desired behaviour of any consumer of joist wishing to use typedoc.
| import { Tag } from "./entities"; | ||
|
|
||
| // Example of using a completely different opts type. Use number so that the type isn't a string/look like a tagged id. | ||
| /** Example of using a completely different opts type. Use number so that the type isn't a string/look like a tagged id. */ |
There was a problem hiding this comment.
NOTE: I explicitly didn't ignore this document, to illustrate that you can provide helpful comments for these if you enhance the default factories.
| @@ -10,6 +10,7 @@ export function generateFactoriesFiles(entities: EntityDbMetadata[]): CodegenFil | |||
| const entityFiles = entities.map(({ entity }) => { | |||
| const name = pascalCase(entity.name); | |||
| const contents = code` | |||
| /** @ignore */ | |||
There was a problem hiding this comment.
The ignores in the codegen files are 100% fine b/c we'd never see them; for the factories, given we "see" this code, I wouldn't mind skipping the ignore here... 🤔 wdyt?
There was a problem hiding this comment.
My thinking with the factories was without the @ignore, you would end up with 100s of entries/pages in the docs. 90+% of which were the vanilla default factories.
Seemed to me that those cluttered documentation with generated cruft. By putting in the @ignore in the codegen step, it allows the maintainer to put in real documentation, should that be valuable. I've done that for three factories which have special behaviours in the RP space so far:
There was a problem hiding this comment.
Fwiw is there an option that docs are opt in instead of opt out? Like only include things in the docs that explicitly have jsdocs?
Granted, our entities do not today ... but, dunno, I think that would be more reasonable even for like the code in our entities, like if we have ~5 methods on the entity, and only 1 of it has docs, then put that one in the docs, and just ignore the others.
There was a problem hiding this comment.
Maybe https://typedoc.org/guides/options/#excludenotdocumented ?
Especially if ^ knew that /** ... */ --> put it in the docs, // ... --> don't put it in the docs; that would be amazing
There was a problem hiding this comment.
I suspect that option would render the docs pretty useless.
For instance, you would then presumably not see any of the fields which exist on an entity, except for those which are defined in the non-codegen file and have an explicit doc comment. So discoverability of things like oh, an Author has a collection of Books would be lost.
There was a problem hiding this comment.
Though, I guess we could change the direction of this PR from ignore things to generate semi-reasonable docs where appropriate 🤔
There was a problem hiding this comment.
Ah yeah, agreed we'd want to see those ... but right, probably pretty to flag them in codegen.
Maybe the most annoying would be all of our Author.ts files that we'd have to like glob in a /** The author entity. */ for all of our ~150 some existing entities? Or at least I assume we'd need to add those, otherwise the entity itself wouldn't show up?
...or I guess it would show up by factor of some of its fields being in the docs, so that would get it pulled in? That's maybe not too bad then?
Adds
/** @ignore */javadocs to some generated types/fields/variables so that they do not show up in typedoc output.