Productize: documentation

[KCarlile]

Background

Guitar Diagram JS should be productized and ready for use by the community. This includes packaging, documentation, properly commented code, etc.

Issues in this pseudo-epic

• Productize: project operations #3
• Productize: packaging #12
• Productize: examples #11
• Productize: documentation #10
• Productize: code quality #9

Acceptance Criteria

• API documentation is available on docs/api-docs.md

• API docs are available for all public functions/methods and members

• Coverage should include (this can be the outline format):

  • guitar-diagrams.js
    • public members
    • public methods/functions
  • guitar-diagrams-config.js
    • public members
    • public methods/functions
  • guitar-diagrams-marker.js
    • public members
    • public methods/functions

• Each section should be listed alphabetically and grouped by type (method, config value)

• Fields for each type should include:

  Field name	Description	Contents	Notes	Presence
  Name	Name of the constructor, member, property, or method	Text		✅Constructor ✅Member ✅Property ✅Method
  Description	Name of the constructor, member, property, or method	Text		✅Constructor ✅Member ✅Property ✅Method
  Parameters	Type and description of the parameter(s).	Text	None if empty	✅Constructor ✅Member ✅Property (set only) ✅Method
  Return Value	Type and description of the return value.	Text	None if empty	❌Constructor ❓Member ✅Property (get only) ❓Method
  Example	Code sample of how to use this API item.	Code		❓Constructor (not for default) ✅Member ✅Property ✅Method
  Notes	Any additional commentary about the API item.	Text	Optional field to be added as needed.	❓Constructor ❓Member ❓Property ❓Method

  Key: ✅Yes, required. ❓Optional. ❌ No, not necessary.

• Remaining documentation has been reviewed and approved (or edited and approved)

  • README.md - general project introduction
  • docs/examples/index.md - documentation home page
  • docs/examples/index.html - Examples HTML page
  • docs/examples/code-owner-docs.md - code owner documentation page

Formatting Template

The formatting template exists between the next two HRs.

---

class-name.js Class

class-name.js Constructors

Constructor(s) in class-name.js go here...

class-name.js Public Properties

Properties in class-name.js go here...

propertyName (get)

Property definition....

• Parameters: None
• Return Value: {type} Description of return value.
• Default Value: {type} 'value'

Example:

console.log('Canvas ID: ' + gdj1.config.canvasID);

propertyName (set)

Property definition....

• Parameters: {type} Description.
• Return Value: None
• Default Value: {type} value

Example:

some.code = 'example';

class-name.js Public Methods

methodName

Description of method....

• Parameters: {type} Description of parameter.
• Return Value: {type} Description of return value. (Or None)

Example:

gdj5.someMethod('someValue);

---

Approach

• Determine the best format for API docs: table or headings (see examples below), or propose a better implementation
• Add API documentation for each JS file's public members and methods to the file docs/api-docs.md (formerly docs/index.md)

Notes

Notes for Chad

For each JS file, document the following:

• Public members: variables that do not start with #
• Public properties: get/set-type methods
• Public methods: functions that do not start with #

You can ignore:

• Private members (starts with #)
• Private methods (starts with #)
• Constructors (except for the default constructor in guitar-diagrams.js)

Be sure to reference default values for any properties by looking at the matching private member (e.g., get someValue() or set someValue(paramSomeValue) would have a private member named #someValue with a default value.

[KCarlile]

@ckreiger1 , I've updated this ticket's description to include the API documentation template for a class in Markdown. As we refine and extend this, we can keep updating the template here.

Edit: Okay, now I've really changed the contents of this ticket to try to help make it more clear. 😄

Another edit: I've just pushed a change to move the API docs part of the content to api-docs.md, so that's the new file in which you'll be primarily working. It's the same thing, but I've just split it into another page. I'll handle the general documentation in docs/index.md, at least for the first pass. I'll have you review and edit later on.

[KCarlile]

Dena showed me an HCG Portal API docs example, for reference:

• Description
• Syntax (method signature)
• Parameters (bulleted list)
• Returns
• Exceptions
• Examples

[KCarlile]

PR #35 to bring develop and 10-productize-documentation in sync as there were many changes and merge conflicts. We'll continue to work on the existing branch (if we can) and issue more PRs into develop.

[KCarlile]

Hey, @ckreiger1! I was looking at the config properties documentation and I realized that in the header for each one (e.g., #### fretMarkerEnabled (set)) we aren't code-ing the property name, but we do it with the class names and code anywhere else.

So, do you think we should change this:

#### fretMarkerEnabled (set)

Exists as a property of the config property...

...to this:

#### `fretMarkerEnabled` (set)

Exists as a property of the config property...

...or do we have too many instances for code-formatted text on the page already and we should be going in the other direction? I'd love to hear your thoughts on this. Thanks!

PS: If we choose to make one of these changes, I can probably do it with regular expressions and find/replace, so don't dive in head first doing that manually if that's what we decide to do.

[KCarlile]

Updated this issue's branch with latest from develop in PRs #39, #46, #49, #50, #53.