locked
What is the API documentation tool for Windows Runtime components?

    Question

  • Searching the web for API documentation tools doesn't lead to a single winner. Still, it looks like Microsoft (at least partly) owns the open source SHFB (Sandcastle Help File Builder).

    However, SHFB doesn't support Windows Runtime components and doesn't want to support them. Here's a quote from the bug resolution (https://shfb.codeplex.com/workitem/34854):

    "It's a low usage case that I'm not going to address."

    If SHFB is not the documentation tool, then what is it? 

    All a component offers is an API, and if that API can't be documented, the component can't be adopted. And if we shipped a component model without an API documentation model, then that component model cannot be publicly adopted.

    So please tell me how I can document my component.

    As we don't have a component marketing model either, my component is free. So the documenting tool better be free too.

    Thanks,
    Zlatko


    This posting is provided "AS IS" with no warranties, and confers no rights.

    Friday, January 10, 2014 5:50 AM

All replies

  • See XML Documentation (C++) or XML Documentation Comments (C#) for the Visual Studio support.

    For help with SHFB (or other 3rd party tools) you'll need to talk to the authors of the tools.

    --Rob

    Saturday, January 11, 2014 12:10 AM
    Moderator

  • The XML comments (articles for which you have referenced) cause the compiler to generate an XML file. That's the first step of the documentation process. 

    Next, that XML file and the assembly are compiled into a human-readable format - a .chm file or a set of .html files. That is done by a tool. That's the kind of tool I'm looking for. One that supports Windows Runtime components.

    Why a special tool? While there are several documentation compilation tools that can work on regular .NET assemblies, the CLI code in Windows Runtime components is generated in a convoluted way that causes those tools to either crash or not generate anything at best.

    I already explained the importance of documentation for components. I don't want to believe Windows released a component model without thinking through API documentation. So please tell me what the documentation story for Windows Runtime component is.


    This posting is provided "AS IS" with no warranties, and confers no rights.

    Saturday, January 11, 2014 5:43 AM