Documentation Feedback

[rosalieucla]

Hi,

Below is feedback on the documentation. Please let us know if you have any questions.
-Rosalie

1. Getting started > README

• several of the file paths are incorrect, e.g. "src/app.router.ts", please fix
• the top of the multi-line code block should have "@component({" in it
• code snippets should use multi-line code blocks (they should not be in-line), i.e. wrap code snippets in ``` instead of `
• please add a code snippet containing the command(s) to use for installing compodoc and generating documentation, also please note version # of both compodoc and NodeJS

2. Modules > AppModule

• The link to "ucla-prrla/ucla-prrla/documentation/modules/routes.html" (in the Imports table) is broken

3. Components, Injectables > SolrService, Pipes

• All class properties should have:
  • public/private annotation (if applicable) that will appear in the documentation
  • type annotation that will appear in the documentation. For example, several of the AdvancedSearchComponent properties ("availableOrders", "initializing_first_time", etc.) do not show any type in the documentation
  • JSDoc with a clear, concise, unambiguous description of the property. For example, several of the AdvancedSearchComponent properties already have JSDocs with descriptions, but they are not clear enough (too many words is better than not enough words)
    • bad: "Available Orders", "Selected Filters"
    • better: "Flag that indicates if page is initializing or not"
• All class methods should have:
  • JSDoc with:
    • a clear, concise, unambiguous description of what the method does
    • @param annotation for each parameter, with name, type, and description, with a hyphen before the description: see http://usejsdoc.org/tags-param.html
    • @returns annotation, if there is a return value

[Hlopec]

Hi all,
Please take a look on this.

[markmatney]

@Hlopec,

Thanks for the update. Items 1 and 2 look good. As for item 3: can you complete the JSDocs in the following components please (particularly, the method parameters with type annotations and descriptions, and method return values)?

• ExhibitionComponent
• ExhibitionsComponent
• HelpComponent

[saslv]

Done. Please check.