Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Allow Documentation for Lists and Maps #9

Closed
norwoodj opened this issue Jul 29, 2019 · 0 comments · Fixed by #10
Closed

Allow Documentation for Lists and Maps #9

norwoodj opened this issue Jul 29, 2019 · 0 comments · Fixed by #10

Comments

@norwoodj
Copy link
Owner

We should allow non-empty lists and maps to be included in the values table with descriptions. This issue asks that we implement the following behavior for values table generation:

  • Only leaf nodes (empty lists, empty objects, strings, ints, and floats) are automatically documented
  • If a list or object has a comment with a description, document it as a value, as you have done here. The default field for lists and objects in this case should be a jsonified string of the field
  • Documenting a list or object in the above fashion stops the automatic documentation of contained fields, that is, they will not be added to the values table. However, if a contained field has a description comment on it, then it will then be included.

An example:

exampleObjectNoDescriptions:
  key: value

exampleListNoDescriptions:
  - key: value

# exampleObjectDescription -- this object will be documented
exampleObjectDescription:
  keyNoDescription: value

  # exampleObjectDescription.keyWithDescription -- this object key will be documented
  keyWithDescription: value

# exampleListDescription -- this list will be documented
exampleListDescription:
  - keyNoDesciption: value

  # exampleListDescription[1].keyWithDescription -- this list item key will be documented
  - keyWithDescription: value

  # exampleListDescription[2] -- this list item will be documented
  - listItemWithDescription: value

Produces

Key Type Default Description
exampleObjectNoDescriptions.key string "value"
exampleListNoDesciptions[0].key string "value"
exampleObjectDescription object {"keyNoDescription": "value", "keyWithDescription": "value"} this object will be documented
exampleObjectDescription.keyWithDescription string "value" this object key will be documented
exampleListDescription list [{"keyNoDescription": "value"}, {"keyWithDescription": "value"}, {"listItemWithDescription": "value"}] this list will be documented
exampleListDescription[1].keyWithDescription string "value" this list item key will be documented
exampleListDescription[2] object {"listItemWithDescription": "value"} this list item will be documented

Note how exampleListDescription.keyNoDesciption and exampleObjectDescription.keyNoDescription aren't documented because the containing object and list themselves have description comments, but the other contained keys are documented because they do have description comments.

norwoodj added a commit that referenced this issue Jul 29, 2019
norwoodj added a commit that referenced this issue Jul 29, 2019
norwoodj added a commit that referenced this issue Jul 29, 2019
norwoodj added a commit that referenced this issue Jul 29, 2019
norwoodj added a commit that referenced this issue Jul 29, 2019
norwoodj added a commit that referenced this issue Jul 29, 2019
norwoodj added a commit that referenced this issue Jul 29, 2019
norwoodj added a commit that referenced this issue Jul 29, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

1 participant