Documentation

[BryanEuton]

Summary of the new feature / enhancement

As a Developer I want to be able to add documentation to my PowerShell Commands. I've looked around for 3rd party utilities to do this, but I haven't found any reliable packages. Red-Gates seemed nice, but doesn't seem to work on .net6. platyPS seems nice, but it is a powershell command not easy hook into Visual Studio Build Process. It also uses markdown files instead of traditional xml comments in the code.
It would be amazing to be able to have something kind of xml based documentation on the class to be pulled into the .dll-Help.xml file.

The most important part of this for me is to be able to add more details to the user for using my commands which includes adding example commands and other details.

Proposed technical implementation details (optional)

Using traditional XML comments, create the necessary .dll-Help.xml so that Get-Help xxx -full will display all of the details pulled from the comments when present.

/// <example>
/// Get-Test -Name "Cool Docs"
/// </example>
[Cmdlet(VerbsCommon.Get, "Test")]
public class TestCommand : PSCmdlet
{
    ...
}

The above would result in the xml file

<command:command
  xmlns:maml="http://schemas.microsoft.com/maml/2004/10"
  xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10"
  xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10">
  <command:details>
    <!--Add name and synopsis here-->
  </command:details>
  <maml:description>
    <!--Add detailed description here-->
  </maml:description>
  <command:syntax>
    <!--Add syntax information here-->
  </command:syntax>
  <command:parameters>
    ...
  </command:parameters>
  <command:inputTypes>
    <!--Add input type information here-->
  </command:inputTypes>
  <command:returnValues>
    <!--Add return value information here-->
  </command:returnValues>
  <maml:alertSet>
    <!--Add Note information here-->
  </maml:alertSet>
  <command:examples>
    Get-Test -Name "Cool Docs"
  </command:examples>
  <maml:relatedLinks>
    <!--Add links to related content here-->
  </maml:relatedLinks>
</command:command>

[kilasuit]

There is a move away from the MAML schema to make use of markdown as it is much easier to support and also able to be hosted on sites like docs.microsoft.com & can be rendered in suitable terminals with recent additions to PowerShell 7 so I would be quite hesitant to see the team spend time on this