enable documenting of Hash / Array attributes

[zhelyan]

This is more to get the discussion started.

Is there are reason to replace Hash/Array attribute defaults with eg. {...} ? If the Hashes/Arrays are large then it is a cookbook design issue (or feature). So why restrict it?

[realityforge]

The main reason was that this plugin was mostly developed to help document really large cookbooks and including the values of these can be particularly large - particularly when you use the attribute_driven style recipes. Hence including that made the documentation unreadable.

If we wanted to include it you could

• Make it a command line option to include the full values, or
• test whether the values are over a certain threshold and if they are shrink it down otherwise include the full value, or
• combination of the above?

Thoughts?

[zhelyan]

I'd vote for a command line option. Attribute values below the attribute?:

node[:foo][:bar] - Description here. Defaults to:

       {
         foo: { 
               name: 'foo bar',
               enabled: true
                  }
       }

[freshmeat123]

Patch for parse hash/array attributes in coobook folder/attributes/*.rb might something like attached

attributes_model.txt

[trinitronx]

Now that Chef 15 deprecated attributes from metadata.rb, it makes sense to have an alternate method for documenting the default values in comments.

I was a bit surprised that any attribute with an Array or Hash value would automatically get these Defaults to [ ... ], Defaults to { ... } appended, regardless of what I had placed in the #<> comments or inside metadata.rb. At first, I thought it was something wrong with my attribute syntax in metadata.rb, but then I found PR #47 which removed this functionality. Seems the README was a bit misleading or out of date w.r.t. that feature.

Even just a simple option to turn off the printing of those fields like default, and choice that are now unable to be filled out would be nice. Then the free-form comments could add whatever they want like: "... (Optional) Defaults to [] empty array"

[realityforge]

I am not actively working on the project atm but happy to accept PRs if they don't break existing users.