How to use it for a documentation generator?

[eestein]

Hi, first all, great job! I got here through the article you wrote for MSDN.
I need exactly what you wrote about in the README. I'm creating a website to display a product's documentation, but I don't wanna use DocFX, SFHB, NDoc, Docu, etc... they all generate HTML and I'd like to just have a simple JSON and be able to use that data into the pages.

Currently, I'm using GetDocumentation to get the XML documentation from my code and ConvertToCSharpSource to display the class' signature.

• My question is, is there an option to use ConvertToCSharpSource for methods as well?
  Do you have an open example of a documentation generator you've created so I could take a look?
• Is there a way to read the docs in a "better" format? I'm asking because GetDocumentation returns the full XML. I'd like something easier to work with like:
  • method's doc: "This method does this and that"
  • parameterX: "Parameter X's description"

Is that possible at all, or should I really read the string response from GetDocumentation and find the needed information?

[ZacharyPatten]

Hi. Thanks for reading the MSDN article and checking out the Towel repo. :)

Is there a way to read the docs in a "better" format?

Currently I only have methods in Towel to get the XML docs in XML string format. Keep in mind that XML docs support much more than just the method and parameter summaries. There are <returns>, <exceptions>, <remarks>, <typeparamref>, <paramref>, <see>, <br/>, <code>, etc. You can see more of the nodes here: https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/recommended-tags. So if you want to convert that into JSON instead of XML, you need a way to represent all features in the JSON.

If you don't care about all of those additional XML nodes and all you want is the <summary> and <param> nodes(and assume there are no nested nodes), then that would be easy to convert from the XML string to JSON. I can make an example of how I might do that, but I would need an example of a method+docs and what you would want the final JSON to look like.

My question is, is there an option to use ConvertToCSharpSource for methods as well?

I assume you mean that you want a ConvertToCSharpSource extension method for MethodInfo that would return the signature of the method without the method body? I currently don't have a method that does that in Towel, but that is something I can add. I would probably call it something like ConvertToCSharpMethodSignature instead though.

[ZacharyPatten]

Also, since you titled the discussion...

How to use it for a documentation generator?

...I just wanted to link to an example where another repo is using the GetDocumentation methods to build an API reference in a website.

• Website (with API Descriptions) https://mudblazor.com/api/button#properties
• GitHub repo https://github.com/MudBlazor/MudBlazor/

That probably won't help you specifically since you want the data in JSON, but it may help others who stumble across this discussion.

[eestein]

Hi Zachary, thank you for your answer.

Keep in mind that XML docs support much more than just the method and parameter summaries.

I do understand that, I probably didn't explain myself in the best way. It would be nice to have those nodes being returned as text, maybe as a Dictionary, since there are so many options. But mainly, for the regular cases, an object could be returned containing the Summary and params. For example:

public class ItemDocumentation
{
    public string Summary {get; set;} // Clean summary with only text, no nodes.
    public string RawData {get; set;} // What is currently returned today.
    public Dictionary<string, string> Parameters {get;set;}
    public Dictionary<string, string> ExtraData {get;set;}
}

This is just an idea.

I assume you mean that you want a ConvertToCSharpSource extension method for MethodInfo that would return the signature of the method without the method body?

Exactly! Currently, I'm doing that by hand, it would be nice to include that in the lib:

Signature = $"{(IsProtected ? "protected" : "public")} {ReturnType} {Name}({printableArgs})";

There are still some things missing there (WIP), like checking for async, override, etc, it's just to confirm the idea.

Thank you also for providing me with the project's links. I'll definitely take a look at it!

Thanks and congrats on the project again!