(PDOC-17) Add support for YARD tags in puppet code #21
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Prior to this commit, most of the HTML created for documenting puppet code was auto-generated by YARD, meaning that it was not always presented in a way that was consistent or easy to read. Now we are explicitly defining the HTML and styling that we want to use when generating documentation for defined types and classes. This means that we can define exactly how we want the output to look so that is more compatible with puppet code.
Prior to this commit there were a few issues in the way information about parameters was collected. The previous implementation relied on parameters and their corresponding comments to be listed in the same order. Now the parameter is matched to the corresponding comment using the parameter name in the comment. Additionally, if a comment is present for a parameter that does not actually exist in the method it will appear as strike through in the HTML.
Prior to this commit if the type for a parameter was not specified in the comment, nothing would be printed. Since we'll soon be adding functionality which will determine the type programmatically, it made more since to leave a place holder rather than nothing at all. As such, the type is now listed as "TBD" if it is not specified by the user in the comment.
Do a bit of renaming and add some comments to make the processing of parameter details a bit more clear. Additionally, update the example in the README so that it will actually be parsed properly by YARD (since YARD does not expect the one line title before the description).
| @@ -0,0 +1,51 @@ | |||
| <h3 class="signature first"> Class: <%= @class_details[:name] %></h3> | |||
There was a problem hiding this comment.
It looks like this always adds a "Class:" sub-heading, which may be misleading when the object is a Defined Type. One thing to consider is that the top-level header inherited from the Ruby module template will say "Definedtype" or "Hostclass" depending on which code object was processed --- so this sub-heading may be redundant.
However, we could definitely clean that top-level description up a bit. Using a description string like "Puppet Class" or "Puppet Defined Type" will probably make more sense than the internal model names which are a bit archaic.
There was a problem hiding this comment.
That's fair, we can probably go ahead and drop this. I'll look into changing the top level description just to make it a little more readable like you suggested.
Prior to this commit there was a header and a sub-header for defined types and classes. This was a little redundant so rather than doing that, remove the sub-header and make the main header more readable.
| # @option opts [String] :fq_name The fully qualified parameter name | ||
| # @option opts [String] :desc The description provided in the comment | ||
| # @options opts [Array] :types The parameter type(s) specified in the comment | ||
| # @options opts [Boolean] :exists? True only if the parameter actually exists and just not just defined in the comment |
There was a problem hiding this comment.
"actually" and "just not just", suggest writing something like "True only if the parameter exists in the documented logic and not just in a comment"
Prior to this commit we were not calling htmlify on the docstring for the description of a puppet class on defined type. This meant that the raw string would be displayed without paying attention to any potential markdown or rdoc formatting present. Now the YARD method htmlify is being called on the docstring so that it will be displayed properly. Additionally clean up an unclear comment and fix a small bug in the way parameter information is processed.
HAIL9000
force-pushed
the
issue/master/PDOC-17_add_support_for_yard_tags
branch
from
23d7d89 to
1fae19e
Compare
hlindberg
added a commit
that referenced
this pull request
Jan 6, 2015
…for_yard_tags (PDOC-17) Add support for YARD tags in puppet code
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Prior to this commit, most of the HTML created for documenting
puppet code was auto-generated by YARD, meaning that it was not
always presented in a way that was consistent or easy to read.
Now we are explicitly defining the HTML and styling that we want
to use when generating documentation for defined types and classes.
This means that we can define exactly how we want the output to look
so that is more compatible with puppet code.
I have yet to add links to any of the details around parameters because it's
not clear to me where those links should go at the moment. It should be
simple to add them though when we decide what we want them to look like.