Compartilhar via

Creating API Documentation

  • Artigo

Some customers have asked my how we create our API docs internally and what tools they can use...  Some of you may have already heard about Sandcastle, but I thought I'd spread the word even more..

Sandcastle enables managed class library developers throughout the world to easily create accurate, informative documentation with a common look and feel. Internally we use Sandcastle to ship .NET Framework documentation and also documentation to https://silverlight.net/quickstarts/ and https://ajax.asp.net/docs/

Sandcastle Highlights:

· Produces quality, comprehensive, familiar MSDN-like documentation.

· Works with or without authored comments.

· Supports Generics and .NET Framework 1.x, 2.x and 3.x

· Sandcastle has 2 main components (MrefBuilder and Build Assembler)

· MrefBuilder generates reflection xml file for Build Assembler

· Build Assembler includes syntax generation, transformation..etc

· Sandcastle is used internally to build .Net Framework documentation

Sandcastle Architecture:

Please see the post at https://blogs.msdn.com/sandcastle/archive/2006/07/28/681209.aspx

Sandcastle wiki site

Molly recently setup a wiki site to share Information about Sandcastle to our customers: www.sandcastledocs.com. On this web site, you can find links to the following information:

Sandcastle Blogs:

https://blogs.msdn.com/sandcastle

Comments

  • Anonymous
    May 16, 2007
    The comment has been removed

  • Anonymous
    May 16, 2007
    Fair point..I beleive we are using SandCastle for .NET Framework 3.5, but I am not 100% sure, I will check. have you used it?  what do you think?

  • Anonymous
    May 16, 2007
    The comment has been removed

  • Anonymous
    May 16, 2007
    Marcos, My name is Anand and I am a Group Manager at Microsoft. My teams builds Sandcastle. We used Sandcastle to ship the Orcas Beta 1 documentation and Framework 3.5. If you are interested in nDoc style GUI it's available for Sandcastle at http://www.sandcastledocs.com. It's a codeplex project written by a customer. Regarding the language selection we are releasing a new documentation design with the next release of Sandcastle to address this issue. If you are interested in additional details please email me at aramATmicrosoft.com. Cheers. Anand..

  • Anonymous
    May 16, 2007
    Here is a pretty GUI for sandcastle http://www.codeplex.com/SHFB

  • Anonymous
    May 17, 2007
    Brad: Can you go into more depth on the process Microsoft uses to generate their documentation, not just specifically the tools (though more info on those would be nice), but the overall process?

  • Are your devs responsible for writing their own code comments?
  • Do your tech writers review every doc comment?  If they do, there not in the actual code are they?
  • Do you use the <include> comment tag to keeps all of the comments external?
  • If you do, how do you manage the process of creating a new comment in the external doc then pointing the code comment to it?
  • How do you manage code snippets in the API docs to ensure their quality? Microsoft is unique in the overall size and quality of the API docs they provide, but there are other orgs out there in somewhat similar situations that would love to learn how you guys do it.
  • Anonymous
    May 17, 2007
    The comment has been removed