(PDOC-35) Support types and providers #46
Conversation
|
I wrote three tests for the providers handler. What else should I test? @HAIL9000 Thoughts? |
iankronquist
changed the title
|
@HAIL9000 this is ready for review. Would you like me to squash it before or after you review it? |
iankronquist
changed the title
|
@iankronquist Let's wait on squashing in case we need to make more changes. We'll definitely want this broken down into several commits when we squash, so let's wait until it's ready to go so we can organize those in a way that makes sense. |
| @@ -55,6 +56,9 @@ def check_required_features | |||
| # all over the terminal. This should definitely not be in real code, but | |||
| # it's very handy for debugging with pry | |||
| #class YARD::Logger; def progress(*args); end; end | |||
| YARD::Tags::Library.define_directive("puppet.provider.param", | |||
There was a problem hiding this comment.
Hmm... not sure how I feel about the name for this directive but I can't think of a better option off the top of my head. May be worth reaching out for suggestions.
There was a problem hiding this comment.
It's a bit long but I like the namespacing.
HAIL9000
changed the title
iankronquist
changed the title
|
I talked with Nick. This isn't sufficient.
|
iankronquist
force-pushed
the
defined-types-and-providers-pdoc-35
branch
2 times, most recently
from
e918198 to
566b758
Compare
iankronquist
changed the title
iankronquist
force-pushed
the
defined-types-and-providers-pdoc-35
branch
from
cbdeb02 to
0a03723
Compare
|
This needs a hell of a rebase but is ready for review. |
|
@nfagerlund ping - are you happy with the changes? |
| if content != node | ||
| # The docstring is either the source stripped of heredoc | ||
| # annotations or the raw source. | ||
| if @heredoc_helper.is_heredoc? content.source |
There was a problem hiding this comment.
As a matter of style:
While it is ok to leave out the () around arguments in a method call, I prefer that there are () everywhere except when the methods are designed to be used in a human friendly DSL style. I find that readability increases in long chains of words (esp when there are also underscores). The one above not so bad, but below there is a line that says:
docstring = @heredoc_helper.process_heredoc content.source
I would prefer that to read:
docstring = @heredoc_helper.process_heredoc(content.source)
Using parentheses also reduces the risk that someone later makes mistakes if there is the need to continue the expression.
(I see no need to go through all of the code to change this, but if you rework it for other reasons, this is something to consider).
|
Sorry for the delay. Yes, I'm happy with what we have! I'm not familiar enough with the code to review it, but the output Ian has shown me is a good first pass at types / providers docs. The foundation is solid enough that we can make further improvements incrementally. I'm 👍 to merge. |
iankronquist
force-pushed
the
defined-types-and-providers-pdoc-35
branch
from
40c4f34 to
14a3c94
Compare
|
Thanks @nfagerlund @HAIL9000 @hlindberg for your feedback and suggestions. |
|
... and a debugging comment creeps in at the last minute. |
| class PuppetX::PuppetLabs::Strings::YARD::CodeObjects::DefinedTypeObject < PuppetX::PuppetLabs::Strings::YARD::CodeObjects::PuppetNamespaceObject | ||
| # A list of parameters attached to this class. | ||
| # @return [Array<Array(String, String)>] | ||
| attr_accessor :parameters | ||
| attr_accessor :type_info | ||
|
|
||
| def to_s | ||
| require 'pry'; binding.pry |
There was a problem hiding this comment.
Looks like we have a bunch of remaining debug statements we should take out (I think these are what's causing the test failures in Travis)
There was a problem hiding this comment.
jk you already noticed this 👍
Adding a provider page and menu * Add categories to html search bar * Require provider handler and object classes * Fetch provider code objects from registry * Add function to generate the provider list * Fetch providers from registry in monkey patches * Add provider templates * Add provider code object * Add provider handler * Add erb file to populate the provider list * Don't emit type information for providers in html * Add tests for provider handler Refactor heredoc: * Remove heredoc annotations * Move heredoc functions into a heredoc helper * Add heredoc helper class
* Print yard documentation statistics for providers * Define a directive which takes a type and a name
* Dunno, I just plowed through a bunch of features * Expect puppet provider in stats output * Fetch default values for Type params and props * Detect allowed values * Add allowed values to test * htmlify scrubbed text * Add features to Type html output * Add infrastructure for types * Add methods for generating lists, etc. * Add provider code object * Add provider handler * Generate list for puppet provider dropdown * Add puppet provider template * Add provider details to puppet type template * Get description properly for types
iankronquist
force-pushed
the
defined-types-and-providers-pdoc-35
branch
from
14a3c94 to
aff2733
Compare
|
@HAIL9000 Travis is green. |
| end | ||
|
|
||
|
|
||
|
|
There was a problem hiding this comment.
Ultra picky comment, but do we need so much white space here?
There was a problem hiding this comment.
Fixed whitespace.
* Float several namevars/ensurables to top of list * Fix minor code style issues
iankronquist
force-pushed
the
defined-types-and-providers-pdoc-35
branch
from
aff2733 to
1991475
Compare
…pdoc-35 (PDOC-35) Support types and providers
|
👍 |
This is not ready yet, but I thought I'd put it up so people can take a look at it.I still need to:mk_resource_method)Handle default values? Is this a requested feature? I see these often mentioned in the docs.