Proposal: documentation as part of assembly

[bbarry]

I'm not sure if this would actually be a language feature or a compiler option or a convention expressed by source generation...

I was thinking about how the current xml based documentation is rather difficult to interact with because it relies on too many potential failure points:

• when reading with source based tooling you need to use roslyn apis to parse and extract the docs
• when attempting to read documentation for an assembly, the assembly build must have chosen to expose the documentation
• when navigating across multiple assemblies via reflection you need to simultaneously navigate multiple xml documents for relevant documentation

It would be nice if there was a way to opt in to a documentation mechanism with:

• minimal effort (perhaps enable a project property or add some system level dependency)
• simple to allow in corporate environments (can't be provided by 1 random person who posts a nuget package)
• an interface that is reasonably compatible with current xml documentation and provides a high level of integration with current introspection mechanisms like reflection and roslyn nodes

I was thinking something very roughly like:

1. A source generator gathers the documentation from a syntax node and provides a partial implementation of that node adding an attribute like [Documentation(typeof(GeneratedDocType), MemberKey = namof(TheSyntaxNode))] and adds another type to the assembly named GeneratedDocType containing the implementation to provide the documentation.
2. The docuementation can be then grabbed at runtime with a type or member reference DocumentationProvider.Lookup(typeof(MyClass))