(PDOC-24) Add basic templates for functions #22
Conversation
Prior to this commit, all the HTML for puppet functions was just generated by YARD as if it were a regular method. Since we ultimately want to have our own custom templates, lay out the groundwork for customizing the templates for functions and update the page headers to be more readable. At the moment the code is functional but contains a lot of duplication which needs to be cleaned up.
Prior to this commit there was a lot of duplicated code around the generation of HTML for templates. Clean up and simplify code by adding an HTMLHelper class with helper functions which can be used in place of repeated logic.
Prior to this commit some of the logic used to extract data from comments for templates was duplicated and a little messy. Create the TemplateHelper class so that can be simplified and cleaned up to make things more readable and efficient.
HAIL9000
changed the title
| if param[:types] | ||
| result << "(" << "<tt>" << param[:types].join(", ") << "</tt>" << ")" | ||
| else | ||
| result << "(<tt>TBD</tt>)" |
There was a problem hiding this comment.
When we discussed how to deal with parameters we decided that if the user did not specify a type we would list it as "TBD" for puppet manifests. I decided to keep it consistent for functions as well, but I'm happy to change it if you think something else would be more appropriate
There was a problem hiding this comment.
3x functions will never have type info per parameter, they only describe the arity. So for those it will be very irritating to see TBD. We cannot really say anything - if we use Any it may be wrong (the function may only accept something else - there is no way to know). So for 3x functions I think we should leave this blank. In other cases 'TBD' is good enough for now - someone may want to change it later to 'unspecified' or something like that. We could run this by UX later, and ask for feedback.
|
Okee dokee, I shall fix the issue around the @param tag for 3x functions and update the comments! 👍 |
Prior to this commit, the @param tag was not supported for 3x functions since we could not derive any information about the parameter from the code itself. Since we would still like users to be able to document parameters if they wish, update the code so that if a parameter is documented in the 3x :doc string it will be displayed in the HTML.
HAIL9000
force-pushed
the
issue/master/PDOC-24_add_basic_templates_for_functions
branch
from
9e42769 to
4127591
Compare
| # @param fq_name [Boolean] does this parameter have a fully qualified name? | ||
| # | ||
| # @return [Hash] The relevant information about each parameter with the following keys/values: | ||
| # {:name => [String] The name of the parameter |
There was a problem hiding this comment.
think you need to indent the continuation of the @return to make it appear in the output for it
Prior to this commit, some of the comments in the code were not as clear as they should have been and in some places comments were not present where they were needed. Clean up existing comments and add some for sections of code that are not very clear. Additionally, some sections of the template for puppet namespaces didn't really make sense to include, especially since we want the source of truth for documentation of 3x functions to be the :doc string which is passed in (not the comment block above the function). Thus, remove some of the unneeded sections from the puppet namespace template.
HAIL9000
force-pushed
the
issue/master/PDOC-24_add_basic_templates_for_functions
branch
from
4127591 to
26945ea
Compare
|
Looks fine, will merge when travis goes green. |
…mplates_for_functions (PDOC-24) Add basic templates for functions
Prior to this commit, all the HTML for puppet functions was just
generated by YARD as if it were a regular method. Since we ultimately
want to have our own custom templates, lay out the groundwork for customizing
the templates for functions and update the page headers to be more
readable.