Open KCarlile opened 1 month ago
@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.
Dena showed me an HCG Portal API docs example, for reference:
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
.
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.
Updated this issue's branch with latest from develop
in PRs #39, #46, #49, #50, #53.
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
3
12
11
10
9
Acceptance Criteria
docs/api-docs.md
guitar-diagrams.js
guitar-diagrams-config.js
guitar-diagrams-marker.js
✅Member
✅Property
✅Method
✅Member
✅Property
✅Method
✅Member
✅Property (set only)
✅Method
❓Member
✅Property (get only)
❓Method
✅Member
✅Property
✅Method
❓Member
❓Property
❓Method
Key: ✅Yes, required. ❓Optional. ❌ No, not necessary.
README.md
- general project introductiondocs/examples/index.md
- documentation home pagedocs/examples/index.html
- Examples HTML pagedocs/examples/code-owner-docs.md
- code owner documentation pageFormatting Template
The formatting template exists between the next two HRs.
class-name.js
Classclass-name.js
ConstructorsConstructor(s) in
class-name.js
go here...class-name.js
Public PropertiesProperties in
class-name.js
go here...propertyName (get)
Property definition....
Example:
propertyName (set)
Property definition....
Example:
class-name.js
Public MethodsmethodName
Description of method....
Example:
Approach
docs/api-docs.md
(formerlydocs/index.md
)Notes
Notes for Chad
For each JS file, document the following:
#
#
You can ignore:
#
)#
)guitar-diagrams.js
)Be sure to reference default values for any properties by looking at the matching private member (e.g., get
someValue()
or setsomeValue(paramSomeValue)
would have a private member named#someValue
with a default value.