Can Wyam generate a report about missing documentation?

I was thinking along the lines of:

• Missing Summary Information
• Missing Examples for Aliases
• etc

For the Addin Documentation. This doesn't have to appear as an actual page on the website, but perhaps as a downloadable artifact?

This sounds to me more of something which would fit for a feature in Cake.AddinDiscoverer.

@Jericho What do you think?

AddinDisco can certainly generate a new report (markdown, Excel, or any format really) as long as I understand where to get the information from.

You would need to inspect aliases of the addins and parse XML documentation for each to inspect if doc is missing, they don't contain examples, etc. Parsing of XML documentation for addins is something which Wyam currently already does for generating the documentation for cakebuild.net, we therefore should also be able to implement it as part of the website documentation generation. But only from scope I think Cake.AddinDiscoverer would be the better place.

Funny, you suggested something similar quite a while ago and it inspired me to attempt to inspect addins using reflection but I didn't succeed. If I remember correctly, I was getting errors because of missing types due to the fact that addins reference packages, which reference other packages, which reference more packages, etc.

I need to revisit the issue and refresh my memory.

Reflection won't help for XML comments, since they are not part of the assembly, but instead written to an XML file. You would need to check for and parse this. This is the part which Wyam already has implemented.

ok but won't I still need to scan the assembly to figure out which class(es) and/or method(s) are decorated with the appropriate Cake attribute?

Sure, you'll need to detect the aliases through reflection and then parse the xml comment from the xml file. Do you think it is worth to implement this all in AddinDiscoverer or better as part of the website generation where we the detection and parsing already have in place?

Detecting the aliases is what I tried when you suggested it (about 2 1/2 years ago) and unfortunately, I failed. I am willing to give it another go. If I succeed, I will be happy to also parse the XML file and generate the report, but if I don't succeed then, sorry: no report for you! ;-)

Benefit of a separate tool from site, is that it wouldn't slow down/take resources from each website build. Also it only needs to run once per version published to NuGet.

@Jericho For reading XML comments you might want to have a look at https://github.com/RicoSuter/Namotion.Reflection which provides an API for it.

Does anybody have a sample of what the report should look like?

How about one an Excel sheet containing one tab per addin, and inside the tab a list like:

| Member name               | Issue                               |
|---------------------------|-------------------------------------|
| MyNamespace.MyClass.Foo   | Summary description misssing        |
| MyNamespace.MyClass.Bar   | Example missing                     |

I wrote something for Bakery a couple of years ago that gets type information without Reflection via Mono.Cecil and maps each member to the XML documentation. Perhaps this could be used to find unmapped members as well. @mholo65 Do you remember what I mean?

@patriksvensson yep, and using Mono.Cecil over reflection have the benefit of not loading the assembly into the app domain. In Bakery we pull out XML docs for addins in order to keep the docs for the generated DSL. This way intellisense will show documentation for generated DSL, which is nice.