0

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";
     }
}
albert
  • 8,285
  • 3
  • 19
  • 32
AechoLiu
  • 17,522
  • 9
  • 100
  • 118
  • 2
    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 Mar 12 '14 at 16:18
  • I has read [IDocumentationProvider@MSDN](http://msdn.microsoft.com/en-us/library/system.web.http.description.idocumentationprovider(v=vs.118).aspx), it returns 'string'. But the [MarkdownDeep](http://www.nuget.org/packages/MarkdownDeep.Full/1.5.0) make the `string` as input and turn it to `IHtmlString`. – AechoLiu Mar 13 '14 at 02:05
  • Now, I modified the `Area\HelpPage\Views\DisplayTemplates`, and turn the `document` string to `@Html.Markdown(document). – AechoLiu Mar 13 '14 at 02:10

1 Answers1

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>
tenbits
  • 7,568
  • 5
  • 34
  • 53
  • 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. – AechoLiu Apr 17 '15 at 08:26
  • 1
    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. – David Chiew Nov 06 '15 at 05:36