Add xml documentation inheritdoc conversion [#245]#337
Add xml documentation inheritdoc conversion [#245]#337fgreinacher merged 31 commits intoTestableIO:masterfrom
Conversation
Setting the XML documentation file through Project Properties/Build only generated the XML documentation file for NET40 and not netstandard1.4 nor netstandard2.0. Adding the property GenerateDocumentationFile and setting it to true generates the documentation for all build types.
This is used to update the xml documentation by replacing the inheritdoc tags with the associated documentation.
This should convert the inheritdoc tags to the documentation in the mscorlib.xml file.
|
Will have to look at what caused the AppVeyor build error tomorrow. |
Fix the environment variable syntax for ps (powershell) rather than cmd.
Calling InheritDoc needed to occur before the nuget package creation, so was moved to the before_build step. PowerShell variables are not resolved if wrapped by single quotation marks, so these have been removed.
|
@fgreinacher This should hopefully be working now, but I don't have a way (that I know of) of checking that the xml documentation has been converted. |
|
Thanks for working on this @robertlarkins. For verification you could download the nupkgs from https://ci.appveyor.com/project/tathamoddie/system-io-abstractions/build/2.1.0.212-tcfasuhb/artifacts, extract them and then look at the “final” contents. |
The InheritDoc call is not working, hopefully this will fix it.
|
@fgreinacher Just done another fix and checked the artifact, the inheritdoc tags have now been replaced, so should be good to go. |
| </ItemGroup> | ||
|
|
||
| <ItemGroup Condition="'$(TargetFramework)' == 'netstandard2.0'"> | ||
| <PackageReference Include="InheritDoc"> |
There was a problem hiding this comment.
It's weird to have this here as a package reference. Its not actually "used" in the project and forces a new dependency on our consumers. Furthermore the version here needs to be in sync with the version mentioned in the appveyor script.
What about doing dotnet add package InheritDoc --version 1.2.0.1 from within the appveyor script? This would make the installation and usage much more local.
There was a problem hiding this comment.
That's a good point, will look into it.
The plan is to install InheritDoc temporarily using appveyor so that it does not get deployed with System.IO.Abstractions.
Attempting to identify the folder InheritDoc is installed into.
|
InheritDoc isn't converting all the inheritdoc tags, so need to investigate why that is... |
This is in attempt to fix the missing inheritdoc conversions.
|
This one looks mergeable without problems. |
|
@ericnewton76 don't merge yet, there's an issue with converting the inheritdoc tags to the actual comments that is being looked into. See here: firesharkstudios/InheritDoc#3 |
The powershell call is not converting the environment variables to their actual values. Adding the quotation marks might help.
The backslashes were causing parsing errors.
|
Wish I had found this half an hour ago: http://www.yamllint.com/ |
Trying a non-powershell approach. If this doesn't work, then back to the forums.
This is based on feedback from the appveyor forum.
|
@fgreinacher @ericnewton76 InheritDoc appears to be fixed and the yaml build script is finally working (after getting help on the appveyor forums). So take a look and see if it's good to go. |
|
Great - so here we go! Thanks for making this work! |
3 participants
This adds the inheritdoc tool to convert the inheritdoc tag in the xml documentation to the associated comments in System.IO. These comments are updated using those found in mscorlib.xml.
Note: The changes to appveyor.yml will need to be checked confirm they are operating correctly on appveyor.