Add language option

[Herrmel]

Hi, I recently had some time to implement the basic functionality of #6 myself. I used your input to make the language an option. When provided it now prioritizes the documentation in the language folders if found.

I had to do some additional changes because I ran in some issues with documentation from microsoft in .net5 where a documentation file for mscorlib.dll exists but there is no language version of it. There also are language versions of netstandard and System.Runtime.dll wich contain mostly the same members. So before my changes the documentation with the member that was first read was used because it was listed first in the xml-Container, wich in my case was mscorlib. Because of that I added a priority-flag to insert language files as well as explicitly provided XmlFiles at earlier postions to the xmldoc-Container since those should be prioritzed.

With this change it worked pretty fine but I only testet with .net5 so far.

Tell me what you think of the changes. Would be nice to have it on nuget.org^^

[saucecontrol]

Hallo!

I won't have any significant time to spend on this for the next couple of weeks, but I gave it a quick look, and it's a good start. :)

I'm not sure I like the idea of the priority flag because it would change the existing behavior of AdditionalDocPaths. I originally meant that to be a way to fill in docs that are missing from the assembly references, and the new behavior would make them override instead. What would you think about tagging imported localized docs with a lang attribute, so that instead of taking the first matching identifier, it could prioritize by lang match as well?

I'm also curious about all the ways localized docs are shipped in netfx reference assembly installations, NuGet packages, etc. Are they typically only identified by being in a folder with the culture name? Do they have a lang attribute in the XML directive inside the doc? And have you seen any docs for how VS/Roslyn resolves localized docs? It would be good to match whatever Roslyn does since this package is meant to emulate that post-compile.

[Herrmel]

I'm not sure I like the idea of the priority flag because it would change the existing behavior of AdditionalDocPaths. I originally meant that to be a way to fill in docs that are missing from the assembly references, and the new behavior would make them override instead. What would you think about tagging imported localized docs with a lang attribute, so that instead of taking the first matching identifier, it could prioritize by lang match as well?

Personally I think this would add another way of using the AdditionalDocPaths. I dont think the possibility to override an existing Member with a self provided one is almost never going to cause any harm. I even think the user expects the task to use his file over anything else if provided. But this is just my opinion and I dont really need the feature so I wouldnt have any problem with changing it up.

I'm also curious about all the ways localized docs are shipped in netfx reference assembly installations, NuGet packages, etc. Are they typically only identified by being in a folder with the culture name?

From the docs I found I think so:
https://docs.microsoft.com/en-us/nuget/create-packages/creating-localized-packages
https://docs.microsoft.com/en-us/dotnet/core/install/localized-intellisense

Do they have a lang attribute in the XML directive inside the doc?

No they dont

And have you seen any docs for how VS/Roslyn resolves localized docs? It would be good to match whatever Roslyn does since this package is meant to emulate that post-compile

See the links mentioned above

[saucecontrol]

Closing, per https://github.com/saucecontrol/InheritDoc/issues/6#issuecomment-1785004722

Thanks for the effort regardless :)