xWaitForADDomain: This resource is missing comment-based help

[johlju]

This resource is missing comment-based help for the functions.

[X-Guardian]

@johlju How can this help be displayed?

[johlju]

We have "debated" this in general in the issue PowerShell/DscResources#253 if we need this or not. The conclusion was that this is not for the users but for the contributors to add notes about design choices. The style guideline also has this entry https://github.com/PowerShell/DscResources/blob/master/StyleGuidelines.md#functions-have-comment-based-help
In reality it is mostly not used in that way unfortunately (with the exception of PSDscResources) so mostly it just the synopsis and the parameters with the same text as in the schema.mof. Helper functions is not documented else where, so that is good that those parameters are documented in the comment-based help.
But the whole comment-based help be or not be could be discussed again since there are new contributors and maintainers since the last time.

Though, I will not enforce that there need to be an .EXAMPLE (saw it in the style guideline just now) . An issue should really be opened to removed that from the style guideline, no maintainer enforces that what I have seen.

[X-Guardian]

OK, no use to end users then. I've been experimenting with the about*.help.txt files that the New-DscResourcePowerShellHelp generates, and these are much more useful for the end user, as they are dynamically built from the MOF data and example files and allow you to run get-help on the resource name to show them. There is currently no mention of these in the style guidelines.
Currently the New-DscResourcePowerShellHelp function outputs these files all to one directory, but could be easily changed to output them to the en-US folder of each DSCResource, which for me seems a more logical location. Get-Help will find the files there.
I think we should update this function and populate the module with these files. What do you think?

[johlju]

I like the idea of adding the `about*.help.txt files to help the ends users. We should also update the GitHub pull request template that these should be updated (so that I remember to enforce it), and also it would be good to open an issue in the DscResource repo for this to be added to the style guideline.

This would not replace the comment-based help though, that I think is still needed for the developers for design choices etc.

[X-Guardian]

Yes, agreed. different audience.

I raised this PR PowerShell/DscResource.Tests#325 to make the New-DscResourcePowerShellHelp function more useful for this. We could then take it further and add a meta-test that checks that the help files are there and are correct...

If you want to raise an issue for the about_help files in this repo, I'll populate all of them from the output of the function.

[RobertCGouge]

I am going to take a shot at this.