red-gate / XmlDoc2CmdletDoc

Create cmdlet XML help files from XML doc comments
Other
63 stars 24 forks source link

Adding globbing/wildcard identification and subsequent generation #54

Closed VonOgre closed 4 years ago

VonOgre commented 4 years ago

Fixes #52 The crux of the fix was noted in the issue itself, in so far that powershell has a [SupportsWildcards] attribute that can be set on a property to indicate that it would honor "globbing".

However, there was some more fallout in that the referenced NuGet package for System.Management.Automation wasn't actually an MS supported version (based on its nuspec description) and all subsequent releases go into something more focused on .NET core. In the interim, I changed the nuget reference to Microsoft.PowerShell.3.ReferenceAssemblies, since it meets the same end, but provides all of the available types from PS v3 and works through 5.1.

There actually seems to be a bug somewhere in Powershell 5.1's help article generator that ignores the "globbing" attribute anyways, so this may be a bit of a moot fix, or globbing is actually only honored on something besides a string parameter type, but better safe than sorry!

ChrisLambrou commented 4 years ago

Many apologies for being so quiet and not responding here in a timely manner. It's been difficult to find time to work on this project over the past few months. Anyway, I've recently been working on a few things that will affect this PR.

First of all, all of the project files have finally been migrated to the modern sdk project format.

Secondly, I've stopped referencing the unsupported version of the System.Management.Automation. That package had been abandoned for a long time, although it's subsequently started to see some activity. Unfortunately for us, it's moved in the direction of only supporting netcoreapp3.1, and whilst Redgate is moving in that direction, we still have plenty of stuff that needs to span multiple target frameworks.

Anyway, the upshot is that it's Microsoft.PowerShell.5.ReferenceAssemblies that's now being referenced, and there are a bunch of conflicts between this branch and master due to the project file conversion. I have some free time on Friday, so I'll try to resolve the conflicts then, unless you're inclined to spend any time on this before then.

Thanks for spending time on this.

VonOgre commented 4 years ago

Absolutely no worries on being quiet! I totally understand being busy and not finding a lot of time for side projects. Given the fact that there seems to be a gremlin in how PowerShell interprets the XML file and ignores the globbing attribute when generating the help output, it's not exactly a pressing fix, but since it was a chipshot to at least say there's appropriate support, I thought I'd toss my hat in the ring. I'll push an update tonight, as my intention wasn't just to introduce more work for you ;)

ChrisLambrou commented 4 years ago

I've just published a new version of the package with this change. It'll take a while for validation, but should appear in the next hour or so. 😃