add typedef and class documentation #148
Conversation
There was a problem hiding this comment.
I like this a lot, but can you use puppet-strings documentation? This allows us to generate a nice REFERENCE.md in an automated way. If you need help with this, we'll gladly help.
| # @param sslproxy_cert_error | ||
| # Defaults to undef. If you pass in a hash of sslproxy_cert_error entries, they will be defined automatically. http://www.squid-cache.org/Doc/config/sslproxy_cert_error/ | ||
| # @param extra_config_sections | ||
| # Defaults to empty hash. If you pass in a hash of `extra_config_section` resources, they will be defined automatically. |
There was a problem hiding this comment.
The defaults to is redundant here. This is what puppet-strings generates:
##### `extra_config_sections`
Data type: `Optional[Hash]`
Defaults to empty hash. If you pass in a hash of `extra_config_section` resources, they will be defined automatically.
Default value: {}
| # @param ssl_bump | ||
| # Defaults to undef. If you pass in a hash of ssl_bump entries, they will be defined automatically. http://www.squid-cache.org/Doc/config/ssl_bump/ | ||
| # @param sslproxy_cert_error | ||
| # Defaults to undef. If you pass in a hash of sslproxy_cert_error entries, they will be defined automatically. http://www.squid-cache.org/Doc/config/sslproxy_cert_error/ |
There was a problem hiding this comment.
Here the default is somewhat useful:
##### `sslproxy_cert_error`
Data type: `Optional[Hash]`
Defaults to undef. If you pass in a hash of sslproxy_cert_error entries, they will be defined automatically. http://www.squid-cache.org/Doc/config/sslproxy_cert_error/
However, we can also move all the static values from params.pp to init.pp and remove it. That means it's clearer in the docs and less to maintain. Static copies of defaults can go out of sync.
| # would result in the following squid refresh patterns: | ||
| # # refresh_pattern fragment for ^ftp | ||
| # refresh_pattern ^ftp: 1440 20% 10080 | ||
| # # refresh_pattern fragment for (/cgi-bin/|\?) | ||
| # refresh_pattern (/cgi-bin/|\?) -i 0 0% 0 |
There was a problem hiding this comment.
This doesn't render that well I think since examples are assumes to be puppet code.
| # refresh_pattern (/cgi-bin/|\?) -i 0 0% 0 | ||
| # | ||
| # | ||
| # @example YAML example |
There was a problem hiding this comment.
I don't know if you can force puppet-strings to use non-puppet examples.
|
Thanks for the reviews, I mostly agree on the improvement suggestions. But I am not sure what my next point of action is. I'd be happy if this gets merged and improved upon later on. |
|
Thanks for your efforts. As I said: this is already a huge improvement over the previous state. |
Pull Request (PR) description
This Pull Requests adds in-file documentation for typedefs and classes, to meet the puppet Style Guide criteria (Documentation on line 1 ).
The typedef documentation was taken from the Readme, with the removal of some of the markdown notation to improve readability.
This Pull Request (PR) fixes the following issues
puppet-lint failure (http://puppet-lint.com/checks/documentation/)