ASP.NET Web API Help Page with markdown comments

Question

I use asp.net WebApi Help Page to generate the document from comments of source code. And I have used doxygen to generate the document before. The doxygen can parse markdown syntax in the comments and output the well formatted documents. But the WebApi Help Page could not parse markdown syntax now.

For example, the foo function's comments contain Markdown comments, and it will be output as ### Markdown comments *It will return "foo" *It always returns "foo" in WebApi Help Page.

public MyApiController : ApiController {
     ///<summary>
     /// It will return "foo"
     /// ### Markdown comments
     /// * It will return "foo"
     /// * It always returns "foo"
     ///</summary>    
     [HttpPost, ActionName("foo")]
     public string Foo() {
         return "foo";
     }
}

I do not know about 'doxygen', but you could write your own implementation of IDocumentationProvider and supply it to HelpPage or you can take a look at the installed HelpPage file Areas\HelpPage\XmlDocumentationProvider.cs and modify it as per your needs — Kiran
– Kiran, Commented Mar 12, 2014 at 16:18
I has read IDocumentationProvider@MSDN, it returns 'string'. But the MarkdownDeep make the string as input and turn it to IHtmlString. — AechoLiu
– AechoLiu, Commented Mar 13, 2014 at 2:05
Now, I modified the Area\HelpPage\Views\DisplayTemplates, and turn the document string to `@Html.Markdown(document). — AechoLiu
– AechoLiu, Commented Mar 13, 2014 at 2:10

tenbits · Accepted Answer · 2015-04-17 08:25:50Z

4

Thanks for the hints, have just modified HelpPageApiModel.cshtml

1) Install some Markdown library from NuGet, like MarkdownDeep

2) Add Helper function. Notice, you should trim lines, as <summery> is parsed as-is with all trailing whitespaces after newlines. Otherwise all markdown lists etc, wont be correctly parsed.

@functions {
    string ToMarkdown(string str)
    {
        var lines = str.Split('\n');
        var whitespaceCount = 0;
        var i = 0; //from 2. Line
        var imax = lines.Count();
        while (++i < imax)
        {
            var line = lines[i];
            if (whitespaceCount != 0)
            {
                lines[i] = line.Substring(whitespaceCount);
                continue;
            }
            var trimmed = line.TrimStart();
            if (trimmed.Length == 0 || trimmed == line) continue;
            whitespaceCount = line.Length - trimmed.Length;
            i--;
        }
        str = string.Join("\n", lines);
        var md = new MarkdownDeep.Markdown {ExtraMode = true, SafeMode = false};
        return md.Transform(str);
    }
}

3) Preprocess the documentation string output

<p>@Html.Raw(ToMarkdown(description.Documentation))</p>

edited Apr 17, 2015 at 8:25

answered Apr 17, 2015 at 8:06

tenbits

8,1186 gold badges40 silver badges58 bronze badges

Sign up to request clarification or add additional context in comments.

2 Comments

AechoLiu Over a year ago

I cannot verify this answer. So I give an up vote first. Now, I don't write C# codes, and asp.net MVC codes anymore. So, I cannot verify this answer.

David Chiew Over a year ago

I have verified this answer and its awesome. I see now why all the extra trimming of white space is necessary after I've tested it out. thanks saved my day.

Collectives™ on Stack Overflow

ASP.NET Web API Help Page with markdown comments

1 Answer 1

2 Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

2 Comments

Your Answer

Sign up or log in

Post as a guest

Related