Jira (PDOC-152) Strings should support the documentation of private classes

6 views
Skip to first unread message

Trevor Vaughan (JIRA)

unread,
Dec 11, 2016, 1:12:02 PM12/11/16
to puppe...@googlegroups.com
Trevor Vaughan created an issue
 
Puppet Strings / New Feature PDOC-152
Strings should support the documentation of private classes
Issue Type: New Feature New Feature
Affects Versions: PDOC 1.0.0
Assignee: Unassigned
Components: DOCS
Created: 2016/12/11 10:11 AM
Priority: Normal Normal
Reporter: Trevor Vaughan

With the advent of contain and assert_private() a consistent group of private classes have arisen.

However, unlike many languages, Puppet private classes need to be documented and exposed to the user in case they want to set some of the more esoteric parameters of the classes.

To this end, I would like to recommend that a Private Puppet Classes be added and that the @private YARD tag be accepted to place classes into this group.

Alternatively, detection of assert_private() could be used to note that a class is private to a module.

Add Comment Add Comment
 
This message was sent by Atlassian JIRA (v6.4.14#64029-sha1:ae256fe)
Atlassian logo

Henrik Lindberg (JIRA)

unread,
Dec 12, 2016, 7:40:02 AM12/12/16
to puppe...@googlegroups.com
Henrik Lindberg commented on New Feature PDOC-152
 
Re: Strings should support the documentation of private classes

Not sure I follow the reasoning here - if you can set the parameters from outside, then the construct is not really private is it?
There is still value in producing documentation of private elements of the language for the purpose of helping those that maintain a module.

Note that there will be proper support for private classes built into the puppet language. When that has been added, the @private yard tag can be inferred for those classes. Don't think it is worth digging out the use of assert_private as that will be replaced by the support in the language itself.

Trevor Vaughan (JIRA)

unread,
Dec 12, 2016, 8:57:02 AM12/12/16
to puppe...@googlegroups.com

Henrik Lindberg You bring up a good point. Count this as my official vote toward adding a protected set of classes.

I use assert_private() to ensure that users can't include classes that won't work without other parts of the module. This way I can strictly control, from the top level, how users should be using the module and it lets me logically split up my module into components.

However, I do *not* want to have to repeat all 5 million parameters at the top level, that defeats a lot of the reason that I'm splitting things off into sub-classes.

What I want is what I currently have, which I guess you could call protected, where I can control the class acesss and inclusion order and I can then allow the setting of various less-used parameters via data binding.

Alternatively, classes could be private with parameters having a flag to be public or something like that. That said, my current parameters are already going over 140 characters and I'm starting to think that .h files are about to come back into style.

Henrik Lindberg (JIRA)

unread,
Dec 12, 2016, 10:28:03 AM12/12/16
to puppe...@googlegroups.com

What would protected mean? I am guessing that you cannot include them (unless from within the module), but you can set parameters via APL ?
The semantics for private has not been determined yet (we only have the keyword reserved at this point) - maybe that should mean that you are allowed to set parameters via APL since the module can, if it does not want to allow that, give all parameters explicitly.

Trevor Vaughan (JIRA)

unread,
Dec 12, 2016, 10:32:04 AM12/12/16
to puppe...@googlegroups.com

Henrik Lindberg Yes, this is exactly what I would need. I would expect my data bindings to work on protected classes but not private classes. Also, probably 99% of my classes (and probably everyone else's) would be protected because nobody wants to do the work to make sure that all parameters are exposed everywhere, nor do we want to deconflict the thing parameter from 4 different subclasses. That way lies reverting to the madness of params.pp.

Henrik Lindberg (JIRA)

unread,
Dec 12, 2016, 10:59:03 AM12/12/16
to puppe...@googlegroups.com

We should have this discussion in PUP-523 as this ticket (PDOC-152) is about how the outcome of that ticket would look like when documented.

Henrik Lindberg (JIRA)

unread,
Dec 12, 2016, 11:02:03 AM12/12/16
to puppe...@googlegroups.com

Thomas Mueller (JIRA)

unread,
Jan 13, 2017, 2:31:02 PM1/13/17
to puppe...@googlegroups.com

Discovered today that the @private tag is non-functionional in puppet classes/defines. It would be nice to somehow specify that a class/define is only thought to be used inside the module and that it is not a public interface (I'm thinking of the module::parms, module::install, module::service classes). Right now I added a "THIS IS A PRIVATE CLASS" heading to make it visible.

Christoph Maser (JIRA)

unread,
Apr 11, 2017, 1:46:02 PM4/11/17
to puppe...@googlegroups.com

I just stumbled across this issue because I wondered why the @private tag does not work.
Is it really necessary have this blocked by the language implementation. It would be beneficial to have a generic way to document that a class/define is not meant to be used independent of actually enforcing it.

Also the readme simply says:
For a complete list of tags, see the YARD Tags Overview. and You can also include any number of YARD tags that hold semantic metadata for various aspects of the code.
with no hint that only a subset of the tags is supported

Chris Tessmer (Jira)

unread,
May 6, 2020, 12:08:03 PM5/6/20
to puppe...@googlegroups.com
Chris Tessmer commented on New Feature PDOC-152

As a >3 year update to this discussion:

  • {{}}@api private has been available in Strings for some time to mark "module elements" like classes as private
  • PUP-523 was just transitioned from "Designing" back to "Open," so the introduction of a protected keyword seems unlikely in the foreseeable future.
This message was sent by Atlassian Jira (v8.5.2#805002-sha1:a66f935)
Atlassian logo
Reply all
Reply to author
Forward
0 new messages