Based on this discussion and the currently existing functions, I’m also really leaning towards the dropping of ‘_hook’. Descriptive names and good docs feel sufficient enough.
In regards to my previous contribution (post_compile_hook), I may rework that PR to remove the ‘_hook’ part before it gets included in an actual release. -- Tom Linkin Professional Services Engineer http://puppetlabs.com/ twitter: @trlinkin On Sunday, September 15, 2013 at 5:55 PM, Adrien Thebo wrote: > On Sat, Sep 14, 2013 at 8:17 PM, badgerious <badge...@hotmail.com > (mailto:badge...@hotmail.com)> wrote: > > Re: the yard docs, I think they are generally pretty good for API docs, and > > it looks like most of the stuff is in fact documented in the code, but not > > appearing in generated output for some reason. I took a quick look but > > didn't see any obvious reason for this. I'd be willing to donate some spare > > time (admittedly a bit scarce at the moment) to making yard docs more > > useful. > > > > Re: renaming existing methods, some of them (e.g. #finish, #finalize) are, > > as far as I'm aware, completely internal and so should be relatively easy > > to change. I think I'd be opposed to the renaming of public api methods > > though (e.g. #flush), since that seems like it would make a big mess of the > > thousands of modules out there using them, even with (especially with?) > > compatibility shims. > > > > Re: naming of new hook methods, it seems like everyone agrees that more > > descriptive is desirable (like the referenced 'post_compile_hook'; tells > > you when to expect the method to be called, and at least hints as to where > > it will be called from). I still kind of dislike '_hook' though; it doesn't > > really help determine the who/when/why of method invocation. > > It doesn't look like `_hook` is getting raving support, so I'm willing to > drop it. What about `at_post_compile` or `post_compile`? With respect to your > original pull request, what about `transaction_teardown` or something like > that? > > And with respect to the yardoc, we could define a new yard tag like > `@callback [caller] description` or something to that. > > -- > Adrien Thebo | Puppet Labs > > -- > You received this message because you are subscribed to the Google Groups > "Puppet Developers" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to puppet-dev+unsubscr...@googlegroups.com > (mailto:puppet-dev+unsubscr...@googlegroups.com). > To post to this group, send email to puppet-dev@googlegroups.com > (mailto:puppet-dev@googlegroups.com). > Visit this group at http://groups.google.com/group/puppet-dev. > For more options, visit https://groups.google.com/groups/opt_out. -- You received this message because you are subscribed to the Google Groups "Puppet Developers" group. To unsubscribe from this group and stop receiving emails from it, send an email to puppet-dev+unsubscr...@googlegroups.com. To post to this group, send email to puppet-dev@googlegroups.com. Visit this group at http://groups.google.com/group/puppet-dev. For more options, visit https://groups.google.com/groups/opt_out.
