dsccommunity
Add and Improve help-comments for all functions
They should use the type of format found here:
https://technet.microsoft.com/en-us/magazine/hh500719.aspx
Also, we can use this issue to discuss whether the help-comment should be placed above the function entirely or at the top of the function, inside the curly braces. Right now we don't have an official standard for DSC resources but the DSC team as a whole mostly leans towards putting them above the function.
Mainly because that's a pretty universal placement across most languages and it de-clutters the function. You should be able to collapse the help-comments whether they're above or inside the function. If that's the main issue, then that's something that we should bring up with the ISE
For me it's about collapsing the help comments with the function, put it within the function I have to click once and everything relating to it is now collapsed out of the way. Where above means I have to click twice for every function.
Just my thoughts.
I'm with @tysonjhayes but that differs from say Java which is above the function
@TravisEz13 @KarolKaczmarek @kwirkykat - do you have anything to add to this discussion?
Help comments should always go above the function.
That way you can keep the function collapsed while you open up the help comment separately to see what the function does, how you should use it, what parameters you should put in, etc. That way it also doesn't add extra lines to the function and its much easier to see how long the actual function is.
Generally, all comments should go above the line/block of code they are referring to, so in this case since the comment about the function, it should go above the function.
It's also much easier for the person reviewing the code to make sure that every function has help comments (which they all should) and that those comments contain the correct parameters and examples if we can see them all right above the function declaration.
