6

While browsing the MSDN documentation for the .NET Framework Class Library (FCL) I've always been amazed by how consistent and fully documented it is. It's a constant companion when developing .NET applications. Most doubts that arise when using the APIs are covered. The contrast with e.g. the older Win32 documentation is striking.

Some examples:

  • Documentation for properties always starts out with either "Gets" or "Gets or sets" to specify accessors.
  • Type parameters start out with: "The type of ...".

Does Microsoft use a documentation convention which is followed for the FCL? If so, is this convention publicly available for me to use as well?

Dynamic
  • 5,746
  • 9
  • 45
  • 73
Steven Jeuris
  • 5,804
  • 1
  • 30
  • 52
  • Microsoft publishes the standard for all Microsoft .NET languages. – Ramhound May 14 '12 at 16:09
  • @Ramhound: In this case, the standard applies to the *language* only, not the documentation. – Steven Evers May 14 '12 at 16:39
  • 1
    To address a few issues: Documentation questions are on-topic here on Programmers. Questions about where to obtain specific style guidelines are also on-topic, if they don't appear to be readily available (meaning by a couple of quick searches using your favorite search engine). It's also clear that [some languages provide style guidelines for in-code documentation](http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#styleguide). I don't see any problems with this question at all. – Thomas Owens May 14 '12 at 16:46
  • 1
    The closest I found is a brief example within the subtopics of http://msdn.microsoft.com/en-us/library/b2s063f7.aspx (specifically http://msdn.microsoft.com/en-us/library/z04awywx.aspx). – Danny Varod May 14 '12 at 17:11
  • 2
    Looking at the .net documentation I'm always amazed how they manage to put so much boilerplate and so little substance in there. IMO the Win32 API documentation is much better that the .net documentation. – CodesInChaos May 14 '12 at 22:09

1 Answers1

5

Yes. There is a spec of sorts. That spec is built into StyleCop.

What it basically does is turn "style" errors (comments, code layout/formatting etc.) into build errors.

You can also include/exclude any rule that you like.

Steven Evers
  • 28,200
  • 10
  • 75
  • 159
  • 1
    Doesn't answer the question - the question is regarding the structure/wording of the text within the documentation. – Danny Varod May 14 '12 at 17:08
  • 1
    @DannyVarod: Yes it does. eg: http://blogs.msdn.com/b/sourceanalysis/archive/2009/08/11/property-headers.aspx note that stylecop and fxcop are different in that regard. – Steven Evers May 14 '12 at 17:37