Type description is not pulled in for OutputType target if type is in a separate DLL

[msorens]

One specifies the output type of a cmdlet by decorating the cmdlet class with the OutputType attribute, having a single argument that is the type that the cmdlet returns. If that type is in the same project (DLL) then the Outputs section of the help content will report it.

Example: Given this source...

/// <summary>
/// <para type="description">Container for xyz.</para>
/// </summary>
public class MyData {... }

/// <summary>
/// <para type="description">Container for xyz.</para>
/// </summary>
[OutputType(typeof(MyData))]
public class Get-Foo: Cmdlet {... }

If MyData is in the same DLL as Get-Foo, then you get this help content:

OUTPUTS
MyData
    Container for xyz.

But if MyData is in a separate DLL, the description paragraph does not render.

[ChrisLambrou]

Yes, that functionality was always a bit half-hearted, and I've never really been happy with it. Here are my main issues:

1. Documentation for the type lacks context. You can only describe what the type represents in general terms, rather that its significance as the output type for any given cmdlet.
2. If you don't own the type (e.g. System.String), you can't document it anyway.

So allowing a type to be documented is only ever a fallback option if more context-specific documentation cannot be found. I'm actually more inclined to remove this capability rather than extending the capability of the code to be able to resolve comments from more than just the cmdlet assembly.

I think it might be better to support something like the following as part of the cmdlet XML docs, though I'm not sure how best to make a distinction between multiple paragraphs associated with the same type or multiple output types. I'm not even sure that difference even matters in the output of the Get-Help cmdlet either.

<para type="output">Output type description</para>

[msorens]

I had noticed your point (2) as well, and your suggestion for the new output paragraph type would ameliorate that as well, which is nice. As to your point (1), that is true, of course, but that could often be adequate, so I have less of an issue with that. And I like the notion of auto-generating bits of documentation whenever possible. :-)

So how about the best of both? Add support for the output paragraph type as you suggest, but if not found and the type is in the cmdlet assembly, fallback to the type's description paragraph as it does now.

[ChrisLambrou]

I've had a look at the code a bit, and could probably extend it to enable the XML Doc comments to be resolved for any assembly. There's some awkwardness baked into the Options class, whereby the XML Doc can be obtained from an arbitrary path, but that's not useful and can be stripped out. That is to say, supporting your original suggestion should be fairly straightforward, and making it a fallback option to a <para type="output"/> element seems like a good idea, too. I'll have a go at it tonight.

[ChrisLambrou]

Well I gave it a try, but got a bit snarled up with the error/issue reporting. I think it's quite important to get the reporting right, as it's there to give guidance about inadequate documentation. I'll probably need to tidy it up a bit. Hmm...

[vbjay]

Along with this, do you know of a way to call get-help MyData or some other cmdlet that would grab the members of the type and use xml comments to show details of the member?

Example:

Imports Microsoft.TeamFoundation.VersionControl.Client
Imports Microsoft.TeamFoundation.WorkItemTracking.Client
''' <summary>
''' <para type="description">An info object that describes a grouping of changes by serverpath and includes any workitems that are related to the changesets.</para>
''' </summary>
Public Class FileChangeInfo
    ''' <summary>
    ''' <para type="description">List of changes made to the file in ServerPath.</para>
    ''' </summary>
    Property Changes As IEnumerable(Of Change)
    ''' <summary>
    ''' <para type="description">Last time the file was checked in.</para>
    ''' </summary>
    Property LastCheckin As Date
    ''' <summary>
    ''' <para type="description">The server path of the file that has changes.</para>
    ''' </summary>
    Property ServerPath As String
    ''' <summary>
    ''' <para type="description">List of work items linked to the changesets.</para>
    ''' </summary>
    Property WorkItems As IEnumerable(Of WorkItem)
End Class

Get-Help TFS_Release_Notes.FileChangeInfo

[ChrisLambrou]

I'm afraid not. This tool is for documenting binary PowerShell cmdlets. This issue is specifically about the help content for cmdlets being able to include text defined for types external to the binary PowerShell module. You're asking for a way to get help text for arbitrary .NET types, other than cmdlet sub-types. That's not something that's ever likely to be supported by PowerShell itself, and not the focus of XmlDoc2CmdletDoc either. There is already a way to obtain help text for .NET types. It's the existing XML Doc syntax and associated .xml documentation file that can be generated for each assembly when it's compiled. Indeed, XmlDoc2CmdletDoc uses a library to extract the XML Doc comments for an assembly. I'm not aware of any PowerShell cmdlets that do the same thing, though.

[vbjay]

Right. It is an output type for a cmdlet. See https://github.com/vbjay/TFS-Release-Notes/blob/master/TFS%20Release%20Notes/Cmdlets/WorkItems/GetWorkItemFiles.vb#L32

[ChrisLambrou]

I'm inclined to think that there are really good cases for pulling in help documentation for a type that's not defined in the same assembly as the main binary PowerShell module. For example, shared domain objects used bby more than just the PowerShell binary module might live in their own assembly. In that instance, it would be reasonable for XmlDoc2CmdletDoc to retrieve help content from multiple modules.

Unfortunately, the last time I attempted this, I rather got caught up in architectural issues in the code. It's architecture wasn't ever really thought out. It simply grew from some fairly hacky script-like code. I think I might spend some time cleaning it all up a bit.

[vbjay]

Thanks. It is in the same assembly.

[ChrisLambrou]

Ah, okay. So is it the case that you'd simply like to have the property and field descriptions rolled up into the description for the type? Something a bit like this?

An info object that describes a grouping of changes by serverpath
and includes any workitems that are related to the changesets.

Includes the following properties:

- Changes  List of changes made to the file in ServerPath.

- LastCheckin  Last time the file was checked in.

- ServerPath  The server path of the file that has changes.

- WorkItems  List of work items linked to the changesets.

Also, can you please confirm that the description of your FileChangeInfo type is appearing in the cmdlet help documentation, and it's just the property/field documentation that's currently not being included?