The .NET standard library docs are a thing of beauty because they intermingle autogenerated javadoc-style documentation with generally well-written freeform "remarks" sections that include more general explanations, context, and code samples.