GithubHelp home page GithubHelp logo

pxtl / xmlcommentmarkdowngenerator Goto Github PK

View Code? Open in Web Editor NEW
50.0 50.0 16.0 88 KB

Generates Markdown from VS XML documentation file - forked from https://gist.github.com/lontivero/593fc51f1208555112e0/forks

License: MIT License

C# 100.00%

xmlcommentmarkdowngenerator's People

Contributors

egoughnour avatar ornatwork avatar pxtl avatar

Stargazers

avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar avatar

Watchers

avatar avatar avatar avatar avatar

Forkers

tynorton giacomelli mrtortoise seesharper robertmclaws mikerains egoughnour sassembla kenhansen01 bmcferrin svallebro mikelau13 cpboyd bigsibling justinwritescode vdaular-dev

xmlcommentmarkdowngenerator's Issues

Exception thrown when Xml String contains XML

I added XmlCommentMarkdownGenerator to my project from NuGet, and ran a compile. The output was:

1>Unhandled Exception: System.Xml.XmlException: Unknown element type "input" ---> System.Collections.Generic.KeyNotFoundException: The given key was not present in the dictionary.
1>   at System.Collections.Generic.Dictionary`2.get_Item(TKey key)
1>   at PxtlCa.XmlCommentMarkDownGenerator.XmlToMarkdown.ToMarkDown(XNode node, String assemblyName)
1>   --- End of inner exception stack trace ---
1>   at PxtlCa.XmlCommentMarkDownGenerator.XmlToMarkdown.ToMarkDown(XNode node, String assemblyName)
1>   at PxtlCa.XmlCommentMarkDownGenerator.XmlToMarkdown.<>c__DisplayClass7_0.<ToMarkDown>b__0(String current, XNode x)
1>   at System.Linq.Enumerable.Aggregate[TSource,TAccumulate](IEnumerable`1 source, TAccumulate seed, Func`3 func)
1>   at PxtlCa.XmlCommentMarkDownGenerator.XmlToMarkdown.ToMarkDown(IEnumerable`1 es, String assemblyName)
1>   at PxtlCa.XmlCommentMarkDownGenerator.TagRenderer.<>c.<.cctor>b__8_6(XElement x, String assemblyName)
1>   at PxtlCa.XmlCommentMarkDownGenerator.XmlToMarkdown.ToMarkDown(XNode node, String assemblyName)
1>   at PxtlCa.XmlCommentMarkDownGenerator.XmlToMarkdown.<>c__DisplayClass7_0.<ToMarkDown>b__0(String current, XNode x)
1>   at System.Linq.Enumerable.Aggregate[TSource,TAccumulate](IEnumerable`1 source, TAccumulate seed, Func`3 func)
1>   at PxtlCa.XmlCommentMarkDownGenerator.XmlToMarkdown.ToMarkDown(IEnumerable`1 es, String assemblyName)
1>   at PxtlCa.XmlCommentMarkDownGenerator.XmlToMarkdown.ExtractNameAndBodyFromMember(XElement node, String assemblyName)
1>   at PxtlCa.XmlCommentMarkDownGenerator.TagRenderer.<>c.<.cctor>b__8_1(XElement x, String assemblyName)
1>   at PxtlCa.XmlCommentMarkDownGenerator.XmlToMarkdown.ToMarkDown(XNode node, String assemblyName)
1>   at PxtlCa.XmlCommentMarkDownGenerator.XmlToMarkdown.<>c__DisplayClass7_0.<ToMarkDown>b__0(String current, XNode x)
1>   at System.Linq.Enumerable.Aggregate[TSource,TAccumulate](IEnumerable`1 source, TAccumulate seed, Func`3 func)
1>   at PxtlCa.XmlCommentMarkDownGenerator.XmlToMarkdown.ToMarkDown(IEnumerable`1 es, String assemblyName)
1>   at PxtlCa.XmlCommentMarkDownGenerator.TagRenderer.<>c.<.cctor>b__8_0(XElement x, String assemblyName)
1>   at PxtlCa.XmlCommentMarkDownGenerator.XmlToMarkdown.ToMarkDown(XNode node, String assemblyName)
1>   at PxtlCa.XmlCommentMarkDownGenerator.Program.Main(String[] args)
1>C:\Users\Nikki\.nuget\packages\pxtlca.xmlcommentmarkdowngenerator\0.2.6270.2853\build\PxtlCa.XmlCommentMarkDownGenerator.targets(10,5): error MSB3073: The command ""C:\Users\Nikki\.nuget\packages\pxtlca.xmlcommentmarkdowngenerator\0.2.6270.2853\build\\..\Tools\PxtlCa.XmlCommentMarkDownGenerator.exe" -i "C:\Dev\CodeFirstWebFramework\bin\Debug\net45\\CodeFirstWebFramework.xml" -o "C:\Dev\CodeFirstWebFramework\..\Docs\CodeFirstWebFramework.GeneratedXmlDoc.md"" exited with code 255.

Invalid markdown link syntax for see cref

The TagRenderer for see cref constructs the following markdown format: [[{1}|{0}]]
This doesn't seem to be a valid link under any markdown specification.
Looking deeper into this, this is a format for seePage. Valid format [{1}]({0}) exists for seeAnchor, but it is used only if the reference name in XML starts with !:#

Am I missing something about the markdown specification or doc comments?
Would you accept a PR that generates universally working markdown fora a doc comment like below?

  • Original doc comment
    /// <summary>
    /// This struct is used to transfer data from <see cref="Class1"/> to <see cref="Class2"/>
    /// </summary>
  • generated XML file
            <summary>
            This struct is used to transfer data from <see cref="T:MyNamespace.Class1"/>
            to <see cref="T:MyNamespace.Class2"/>
            </summary>
  • Current output of the tool
 This struct is used to transfer data from [[| T:MyNamespace.Class1]] to [[|T:MyNamespace.Class2]]

  • Current output of the tool renders as
    This struct is used to transfer data from [[| T:MyNamespace.Class1]] to [[|T:MyNamespace.Class2]]

  • Proposed output of the tool

 This struct is used to transfer data from [Class1](#MyNamespace.Class1) to [Class2](#MyNamespace.Class2)
  • Proposed output of the tool would render as
    This struct is used to transfer data from Class1 to Class2

Code is not documented

There is a certain level of irony in a codebase that is designed to turn XML documentation comments into Markdown not having any XML documentation comments that could themselves be turned into Markdown. 😄

Crashes from paramrefs

Cool project - but when processing documentation that contains <paramref/>s, it crashes with:

Unhandled Exception: System.Xml.XmlException: Unknown element type "paramref" - - -> System.Collections.Generic.KeyNotFoundException: The given key was not present in the dictionary.
   at System.Collections.Generic.Dictionary`2.get_Item(TKey key)
   at PxtlCa.XmlCommentMarkDownGenerator.XmlToMarkdown.ToMarkDown(XNode node, String assemblyName)
   --- End of inner exception stack trace ---
   at PxtlCa.XmlCommentMarkDownGenerator.XmlToMarkdown.ToMarkDown(XNode node, String assemblyName)
   at PxtlCa.XmlCommentMarkDownGenerator.XmlToMarkdown.<>c__DisplayClass7_0.<ToMarkDown>b__0(String current, XNode x)
   at System.Linq.Enumerable.Aggregate[TSource,TAccumulate](IEnumerable`1 source, TAccumulate seed, Func`3 func)
   at PxtlCa.XmlCommentMarkDownGenerator.XmlToMarkdown.ToMarkDown(IEnumerable`1 es, String assemblyName)
   at PxtlCa.XmlCommentMarkDownGenerator.XmlToMarkdown.ExtractNameAndBody(String att, XElement node, String assemblyName)
   at PxtlCa.XmlCommentMarkDownGenerator.TagRenderer.<>c.<.cctor>b__8_15(XElement x, String assemblyName)
   at PxtlCa.XmlCommentMarkDownGenerator.XmlToMarkdown.ToMarkDown(XNode node, String assemblyName)
   at PxtlCa.XmlCommentMarkDownGenerator.XmlToMarkdown.<>c__DisplayClass7_0.<ToMarkDown>b__0(String current, XNode x)
   at System.Linq.Enumerable.Aggregate[TSource,TAccumulate](IEnumerable`1 source, TAccumulate seed, Func`3 func)
   at PxtlCa.XmlCommentMarkDownGenerator.XmlToMarkdown.ToMarkDown(IEnumerable`1 es, String assemblyName)
   at PxtlCa.XmlCommentMarkDownGenerator.XmlToMarkdown.ExtractNameAndBodyFromMember(XElement node, String assemblyName)
   at PxtlCa.XmlCommentMarkDownGenerator.TagRenderer.<>c.<.cctor>b__8_4(XElement x, String assemblyName)
   at PxtlCa.XmlCommentMarkDownGenerator.XmlToMarkdown.ToMarkDown(XNode node, String assemblyName)
   at PxtlCa.XmlCommentMarkDownGenerator.XmlToMarkdown.<>c__DisplayClass7_0.<ToMarkDown>b__0(String current, XNode x)
   at System.Linq.Enumerable.Aggregate[TSource,TAccumulate](IEnumerable`1 source, TAccumulate seed, Func`3 func)
   at PxtlCa.XmlCommentMarkDownGenerator.XmlToMarkdown.ToMarkDown(IEnumerable`1 es, String assemblyName)
   at PxtlCa.XmlCommentMarkDownGenerator.TagRenderer.<>c.<.cctor>b__8_0(XElement x, String assemblyName)
   at PxtlCa.XmlCommentMarkDownGenerator.XmlToMarkdown.ToMarkDown(XNode node, String assemblyName)
   at PxtlCa.XmlCommentMarkDownGenerator.Program.Main(String[] args)```

Migrate test project to XUnit?

Very minor thing, just for convenience, to make the project more portable?
Tried to quickly build in Mono, and found that unit-test project depends on MSTest.

Nuget Package - Multi Project Solutions

Hey Guys,

I think there maybe two issues:

  • When you install the Nuget Package, is it meant to append the Target to each Project in a solution? I have a multi-project Solution and the Target wasnt appended (but the package itself with the exe did install in the solutions folder.
  • I went to amend the my Project and include the Target information. Your Target is presuming the package folder sits with the Project folder, which mine doesnt, its which the Solution Directory.

The following target worked for me, note the ItemGroup setting the package directory based on the $(SolutionDir) macro.

 <Target Name="AfterBuild">
    <ItemGroup>
      <ExeDirForPxt Include="$(SolutionDir)packages\PxtlCa.XmlCommentMarkDownGenerator*\tools\PxtlCa.XmlCommentMarkDownGenerator" />
    </ItemGroup>
    <Warning Condition="!Exists('$(MSBuildProjectDirectory)\$(OutputPath)\$(AssemblyName).xml')" Text="PxtlCa.XmlCommentMarkDownGenerator can't generate Markdown: Can't find Xml file matching assembly name.  Please confirm that your project file is configured to output the Xml documentation file in this build configuration." File="$(MSBuildProjectDirectory)\$(OutputPath)\$(AssemblyName).xml" />
    <MakeDir Directories="$(MSBuildProjectDirectory)\Docs" />
    <Exec Command="@(ExeDirForPxt) -i $(MSBuildProjectDirectory)\$(OutputPath)$(AssemblyName).XML -o $(MSBuildProjectDirectory)\Docs\$(AssemblyName).GeneratedXmlDoc.md" Condition="Exists('$(MSBuildProjectDirectory)$(OutputPath)$(AssemblyName).xml')" />
    <Message Importance="high" Text="PxtlCa.XmlCommentMarkDownGenerator created file: $(MSBuildProjectDirectory)\Docs\$(AssemblyName).GeneratedXmlDoc.md" Condition="Exists('$(MSBuildProjectDirectory)$(OutputPath)$(AssemblyName).xml')" />
  </Target>```

Unhandled Exception

Hi!

I have a "KeyNotFoundException: The given key was not present in the dictionary."

I think that typeparam is missing in the dictionary but not sure as the exception is not informative enough.

.targets file does not handle paths with spaces.

When using the NuGet package, the .targets file does not handle paths that have spaces in them. The executable command in the .targets file should have its input and output parameters wrapped in quotes.

Is there a way to put the output somewhere different?

My solution, source and csproj are in the same directory - the top level directory of my project.

I would like to generate the docs somewhere inside my project folder, rather than in ../Docs. Is there any way to change this?

Nuget package does note create a markdown file

Hi

I have a project with xml docs enabled in both debug and release. I get xml files generated when I build.
I have now installed XmlCommentMarkDownGenerator

Install-Package PxtlCa.XmlCommentMarkDownGenerator

Now when I rebuild I do not see any markdown files generated anywhere. I dont see a Docs folder next to the solution folder. Also, I dont see anything added to the csproj file ?

Generic types and parameters are not handled properly

Given the following example:

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>Example.Core</name>
    </assembly>
    <members>
        <member name="T:Example.Core.MessageBus.MessageEnvelope`1">
            <summary>
            Represents a wrapper for an Entity that will be published to the MessageBus Queue.
            </summary>
            <typeparam name="T">The type of the Entity to be published.</typeparam>
        </member>
        <member name="P:Example.Core.MessageBus.MessageEnvelope`1.AttemptsCount">
            <summary>
            The number of times the system has previously attempted to process this message.
            </summary>
        </member>
        <member name="P:Example.Core.MessageBus.MessageEnvelope`1.DatePublished">
            <summary>
            The Date and Time in UTC that this nessage was published to the queue.
            </summary>
        </member>
        <member name="P:Example.Core.MessageBus.MessageEnvelope`1.Entity">
            <summary>
            The Entity that is to be included in the payload.
            </summary>
        </member>
        <member name="P:Example.Core.MessageBus.MessageEnvelope`1.Id">
            <summary>
            A <see cref="T:System.Guid"/> uniquely identifying this message on the queue. Helps when looking at logs or correlating from telemetry. 
            </summary>
        </member>
        <member name="P:Example.Core.MessageBus.MessageEnvelope`1.ProcessLog">
            <summary>
            The processing log for this particular message.
            </summary>
        </member>
        <member name="M:Example.Core.MessageBus.MessageEnvelope`1.#ctor(`0)">
            <summary>
            Creates a new instance for a given Entity.
            </summary>
            <param name="entity">The entity to add to the payload.</param>
        </member>
    </members>
</doc>

There needs to be a way to complete the Type name with the proper Generic parameters. In the example above, the first <member> node needs to become MessageEnvelope<T>.

This means that the processing needs to be more complex. the number after the accent mark describes the number of generic parameters passed in. So the code needs to parse the type, look for the accent mark, and if it's there, generate a comma separated format string (<{0}, {1}>), that can then be used in s string.Format command against the <typeparam> nodes.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.