XMLDOCS, YAML, JSON

Standards for Documentation.

XMLDOCS

In Visual C# you can create documentation for your code by including XML tags in special comment fields in the source code directly before the code block they refer to. For example:

/// <summary>
///  This class performs an important function.
/// </summary>
public class MyClass{}

When you compile with /doc the compiler will search for all XML tags in the source code and create an XML documentation file. To create the final documentation based on the compiler-generated file, you can create a custom tool, or use a tool such as Sandcastle.

YAML

Is a Human-readable data serialization, means “YAML Ain’t Markup Language”

receipt:     Oz-Ware Purchase Invoice
date:        2007-08-06
customer:
given:   Dorothy
family: Gale

items:
 - part_no:   A4786
   descrip:   Water Bucket (Filled)
   price:     1.47
   quantity: 4

 - part_no:   E1628
   descrip:   High Heeled "Ruby" Slippers
   size:      8
   price:     100.27
   quantity: 1

bill-to: &id001
 street: |
         123 Tornado Alley
         Suite 16
 city:   East Centerville
 state: KS

ship-to: *id001

specialDelivery: >
 Follow the Yellow Brick
 Road to the Emerald City.
 Pay no attention to the
 man behind the curtain.

— – # ==========================================
— – Author:
— – Create date:
— – Description:
— – # ==========================================

/**
# ==========================================
Author:
Create date:
Description:
# ==========================================
**/

JSON
JavaScript Object Notation, is a text-based open standard designed for human-readable data interchange.

/**
{
  "returns": "1 if whitespace, otherwise 0,"
  "example": [
   {
    "code": "Select dbo.IsSpace('how many times must I tell you')"
   },
   {
    "code": "Select dbo.IsSpace(' []{}\"!@#$%')
   }
  ],
 "summary": "IsSpace string Function Returns Non-Zero"
}
*/

Extracted from SQL Server Team-based Development

Advertisements
This entry was posted in Uncategorized and tagged , , , . Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s