| As a Module Developer
I want to be able to document my type alias struct parameters
So that my module consumers can understand the purpose of the struct and each parameter within it. Possibly related to PDOC-226 & PDOC-215 Glenn Sarti asked me to C/P our slack discussion so that there would be context of the desired feature capability. (see Below).
bstopp 10:07 PM
I was thinking that the alias could/should be replaced if i provide any @param directives. And maybe then pdk can raise a warning about not having any custom param descriptions for type => structs and an error if one param description is provided but not all are defined? WDYT?
10:09 PM
the alias is informational but not very useful to consumers - module developers should be providing meaningful docs on the params in the structs
Glenn Sarti 10:09 PMfirstly, I think I understand your concern...what I'm thinking is, that technically those are data type aliases. So I'm trying to figure out what the ramifications are
10:10 PM
I wonder if Yard even cares ...
bstopp 10:10 PMmaybe i’m abusing the type aliases 
Glenn Sarti 10:10 PMNah... you're not
10:10 PM
as in what you're doing is legit
10:10 PM
bstopp 10:10 PM
Glenn Sarti 10:10 PMit's that this isn't the only case
10:10 PM
Struct, Object and I think another one will have the same problem
10:11 PM
but parsing that it going to be a major pain in the bum (edited)
10:11 PM
e.g. what if you had nested structs 
bstopp 10:11 PMmakes sense - i am trying to figure out how I should be provding guidance to my module consumers about the structs, so they know what/how to build their hiera data correclty
10:11 PM
boo, Nest structs, while valid, are probably a code smell
10:11 PM
IMHO
Glenn Sarti 10:11 PMdoes Variant[String, Struct[....]]
10:12 PM
How would I express that ... hrmm
bstopp 10:12 PMAhh. i see your point.
10:12 PM
but that isn’t a named struct, so does it have the same consideration? (edited)
Glenn Sarti 10:13 PM
10:13 PM
Just spitballing edge cases
bstopp 10:13 PMno, makes sense to consider all the possibiliites
Glenn Sarti 10:13 PMthat's why for my Version 1 implementation just went "Spit out a string"
bstopp 10:13 PM
Glenn Sarti 10:14 PMBetter than before - 
10:14 PM
I wonder if Yard tagging could be interspersed into the type definition
10:14 PM
Puppet may not like that
bstopp 10:14 PMmaybe v 1.5 a reordering? - eg: i put the params on the docs, and it spit out yard info, here’s what the markdown looks like:
Glenn Sarti 10:15 PMSo something like
Type xxx = Variant[
String,
Struct[
# @param ....
blah =>
]
]
bstopp 10:15 PM
Entry.
### Dispatcher::Farm::RendererRenderer attributes hash. Defines the parameters used to configure the /renderer directive of a farm.Alias of `Struct[{
Click to expand inline (22 lines)
10:15 PM
oh, i didn’t do it that way, i was doing it like….
Glenn Sarti 10:15 PMI know I don't have the code for that
bstopp 10:16 PM
- Renderer attributes hash. Defines the parameters used to configure the /renderer directive of a farm.
#
- @summary A hash of renderer attributes.
- Used to configure the `/renderer` parameter instance of a Farm.
#
- @param hostname
- The hostname for the renderer.
#
type Dispatcher::Farm::Renderer = Struct[
10:16 PM
puppet strings did the rest - i was just seeing what happend when i did this - 
Glenn Sarti 10:16 PMThat example you give is fine if and only if it's an alias of Struct
bstopp 10:16 PMYeah i think you just lost me
Glenn Sarti 10:17 PMS'all good
bstopp 10:17 PMooh, i get you
10:17 PM
your type is either a string or a struct
Glenn Sarti 10:17 PMYeah
bstopp 10:17 PMHuh. Never thought of doing that
Glenn Sarti 10:17 PMwhich wouldn't be that common ... but
10:17 PM
it's still legit
10:17 PM
or Optional[Struct...]
10:18 PM
which would be more common
|
