[Last Call] Learn how to a build a cloud-first strategyRegister Now

x
?
Solved

sandcastle xml tags

Posted on 2009-04-24
32
Medium Priority
?
2,546 Views
Last Modified: 2013-11-26
I am looking for a list of sandcastle xml tags.  The only promising link I found is blocked by our company's security policy.
0
Comment
Question by:dchau12
  • 29
  • 3
32 Comments
 
LVL 11

Expert Comment

by:bmatumbura
ID: 24224932
0
 

Author Comment

by:dchau12
ID: 24225013
Awesome.  This was the link I found.  All three options are blocked by my company's security.  I cant download PDF files, cant download you zip file.  bummer.
0
 

Author Comment

by:dchau12
ID: 24225024
can you copy and paste the tags?
0
Microsoft Certification Exam 74-409

Veeam® is happy to provide the Microsoft community with a study guide prepared by MVP and MCT, Orin Thomas. This guide will take you through each of the exam objectives, helping you to prepare for and pass the examination.

 
LVL 11

Expert Comment

by:bmatumbura
ID: 24225094
If I copy and paste the document will lose the formatting.

Are all attachment types blocked?  Should I just go ahead and paste?
0
 
LVL 11

Expert Comment

by:bmatumbura
ID: 24225120
The tags have long descriptions... I will selectively copy and paste the descriptions I think could be useful in the following posts:

Tag: <c> .......................................................................................................................................................... 19
Tag: <code> .................................................................................................................................................... 20
Tag: <event> ................................................................................................................................................... 26
Tag: <example> .............................................................................................................................................. 27
Tag: <exception> ............................................................................................................................................ 28
Tag: <exclude> ................................................................................................................................................ 29
Tag: <filterpriority> ......................................................................................................................................... 30
Tag: <include> ................................................................................................................................................ 31
Tag: <list> ....................................................................................................................................................... 33
Tag: <note> .................................................................................................................................................... 34
Tag: <overloads> ............................................................................................................................................ 35
Tag: <para> .................................................................................................................................................... 37
Tag: <param> ................................................................................................................................................. 39
Tag: <paramref> ............................................................................................................................................. 40
Tag: <permission> ........................................................................................................................................... 41
Tag: <preliminary> .......................................................................................................................................... 42
Tag: <remarks> ............................................................................................................................................... 43
Tag: <returns> ................................................................................................................................................ 44
Tag: <see> ...................................................................................................................................................... 45
Tag: <seealso> ................................................................................................................................................ 49
Tag: <summary> ............................................................................................................................................. 52
Tag: <threadsafety> ........................................................................................................................................ 53
Tag: <typeparam> ........................................................................................................................................... 54
Tag: <typeparamref> ...................................................................................................................................... 55
Tag: <value> ................................................................................................................................................... 56
0
 
LVL 11

Expert Comment

by:bmatumbura
ID: 24225129
Tag Descriptions
Tag: <c>
Type: Inline
Applies To: Can be used inline within any other markup.
Defined By: Microsoft
Syntax: <c>text</c>
Parameters:
text:
The text you would like to indicate as code.
Remarks:
" The <c> tag gives you a way to indicate that text within a description should be marked as code.
" Use the <code> tag to indicate multiple lines as code.
Example:
/// <summary>
/// <c>Increment</c> method increments the stored number by one.
/// </summary>
public void Increment()
{ number++; }
0
 
LVL 11

Expert Comment

by:bmatumbura
ID: 24225146
Tag: <code>
Type: Inline
Applies To: Can be used inline within any other markup.
Defined By: Microsoft, NDoc, Sandcastle
Syntax:
Microsoft/Sandcastle:
<code>content</code>
0
 
LVL 11

Expert Comment

by:bmatumbura
ID: 24225152
Tag: <event>
Type: Top-Level
Applies To: Method
Defined By: NDoc
Syntax: <event cref="member">description</event>
Parameters:
cref="member":
" A reference to an event that is available from the current compilation environment.
" The compiler checks that the given event exists and translates member to the canonical
element name in the output XML.
" member must appear within double quotation marks (" ").
description:
A description of the event.
Remarks:
" This section defines the events that can be raised by the method.
" There can be multiple <event> tags per method.
Example:
/// <summary>
/// Summary for the class
/// </summary>
/// <event cref="SampleEventHandler">Sample Event</event>
public class Publisher
{
// Declare the delegate (if using non-generic pattern).
public delegate void SampleEventHandler( object sender, SampleEventArgs e );
// Declare the event.
public event SampleEventHandler SampleEvent;
// Wrap the event in a protected virtual method
// to enable derived classes to raise the event.
protected virtual void RaiseSampleEvent()
{
// Raise the event by using the () operator.
SampleEvent( this, new SampleEventArgs( "Hello" ) );
}
}
0
 
LVL 11

Expert Comment

by:bmatumbura
ID: 24225160
Tag: <example>
Type: Top-Level
Applies To: All types and members.
Defined By: Microsoft
Syntax: <example>description</example>
Parameters:
description:
A description of the code sample.
Remarks:
" The <example> tag lets you specify an example of how to use a method or other library
member.
" This commonly involves using the <code> tag.
Example:
/// <summary>
/// The GetZero method.
/// </summary>
/// <example>
/// This sample shows how to call the GetZero method.
/// <code>
/// class TestClass
/// {
/// static int Main()
/// { return GetZero(); }
/// }
/// </code>
/// </example>
public static int GetZero()
{ return 0; }
0
 
LVL 11

Expert Comment

by:bmatumbura
ID: 24225166
Tag: <exception>
Type: Top-Level
Applies To: Property, Method, Event, Operator, Type Conversion
Defined By: Microsoft
Syntax: <exception cref="member">description</exception>
Parameters:
cref="member":
" A reference to an exception that is available from the current compilation environment.
" The compiler checks that the given exception exists and translates member to the canonical
element name in the output XML.
" member must appear within double quotation marks (" ").
description:
A description of the exception.
Remarks:
" The <exception> tag lets you specify which exceptions can be thrown.
" This tag can be applied to definitions for methods, properties, events, and indexers.
Example:
/// comment for class
public class EClass : System.Exception
{
// comment for class
}
/// comment for class
class TestClass
{
/// <exception cref="System.Exception">Thrown when...</exception>
public void DoSomething()
{
try
{
}
catch (EClass)
{
}
}
0
 
LVL 11

Expert Comment

by:bmatumbura
ID: 24225173
Tag: <exclude>
Type: Top-Level
Applies To: All Types and Members.
Defined By: NDoc, Sandcastle Help File Builder
Syntax: <exclude/>
Parameters:
None
Remarks:
" This tag takes precedence over any visibility options.
" Note that Sandcastle does not support this tag. Instead, it uses an API filter in the
MRefBuilder.config file to specify which namespaces, types, and members should be excluded.
" The Sandcastle Help File Builder will use this tag if it finds it and will automatically add the marked
members to the API filter. It also provides support for the API filter directly (the ApiFilter property in
version 1.5.1.0 and after).
The dnrTV (dot Net Rocks TV) Sandcastle episode contains a short explanation of the APIFilter
element and its usage (for links to the dnrTV Sandcastle episode, see the Resources section of this
document).
The API Filter offers the ability to filter namespaces, types and members so that their HTML topics
are not generated by the BuildAssembler.exe utility. Topics are filtered by their API names in the
apiFilter element of the MRefBuilder.config file.
The MRefBuilder.exe program outputs an xml file with reflection information for a set of input
assemblies, which is then processed using XSL transformations and input into the
BuildAssembler.exe utility to generate the HTML topics.
The API Filter is used to prevent specific reflection information from being added to the reflection
file, therefore BuildAssembler.exe will not generate the corresponding HTML topics.
Generic types and members can be filtered by referencing their names using compiler syntax (e.g.,
MyGenericType`1). Individual method overloads cannot be filtered since signatures are not
currently supported.
Example:
/// <summary>
/// The GetZero method.
/// </summary>
/// <exclude/>
public static int GetZero()
{ return 0; }
0
 
LVL 11

Expert Comment

by:bmatumbura
ID: 24225179
Tag: <filterpriority>
Type: Top-Level
Applies To: Method
Defined By: Microsoft
Syntax: <filterpriority>value</ filterpriority >
Parameters:
value:
" Used by the Visual Basic editor in order to determine whether a member should appear on the
Common or All tab when the completion list is shown.
Remarks:
None
Example:
/// <summary>
/// Loads the XML.
/// </summary>
/// <filterpriority>1</filterpriority>
public void LoadXML( string XML )
{
if (string.IsNullOrEmpty(XML))
{throw new ArgumentNullException();}
}
0
 
LVL 11

Expert Comment

by:bmatumbura
ID: 24225193
Tag: <include>
Type: Top-Level
Applies To: All Types and Members.
Defined By: Microsoft
Syntax: <include file='filename' path='tagpath[@name="id"]' />
Parameters:
filename:
" The name of the file containing the documentation.
" The file name can be qualified with a path.
" Enclose filename in single quotation marks (' ').
tagpath:
" The path of the tags in filename that leads to the tag name.
" Enclose the path in single quotation marks (' ').
name:
The name specifier in the tag that precedes the comments; name will have an id.
id:
" The ID for the tag that precedes the comments.
" Enclose the ID in double quotation marks (" ").
Remarks:
" The <include> tag lets you refer to comments in another file that describe the types and
members in your source code. The comments are imported into the generated XML comments
file at build time by the compiler.
" This is an alternative to placing documentation comments directly in your source code file.
" The <include> tag uses the XML XPath syntax.
" Refer to XPath documentation for ways to customize your <include> use.
Tag: <include> [continued]
Example:
NOTE: This is a multi-file example.
The first file, which uses <include>, is listed below:
/// <include file='XML_include_tag.doc' path='MyDocs/MyMembers[@name="test"]/*' />
class Test
{
static void Main()
{ }
}
/// <include file='XML_include_tag.doc' path='MyDocs/MyMembers[@name="test2"]/*' />
class Test2
{
public void Test()
{ }
}
The second file, XML include tag.doc, contains the following documentation comments:
<MyDocs>
<MyMembers name="test"><summary>The summary for this type.</summary></MyMembers>
<MyMembers name="test2"><summary>The summary for this other type.</summary></MyMembers>
</MyDocs>
Compiler Output:
<?XML version="1.0"?>
<doc>
<assembly>
<name>XML_include_tag</name>
</assembly>
<members>
<member name="T:Test">
<summary>
The summary for this type.
</summary>
</member>
<member name="T:Test2">
<summary>
The summary for this other type.
</summary>
</member>
</members>
</doc>
0
 
LVL 11

Expert Comment

by:bmatumbura
ID: 24225197
Tag: <list>
Type: Inline
Applies To: Can be used inline within any other markup.
Defined By: Microsoft
Syntax: <list type="bullet" | "number" | "table">
<listheader>
<term>term</term>
<description>description</description>
</listheader>
<item>
<term>term</term>
<description>description</description>
</item>
</list>
Parameters:
type=
The type of list to be created (bullet, number or table)
term:
The term to that will be defined in description.
description:
Either an item in a bullet or numbered list or the definition of a term.
Remarks:
" The <listheader> block is used to define the heading row of either a table or definition list.
" When defining a table, you only need to supply an entry for term in the heading.
" Each item in the list is specified with an <item> block.
" When creating a definition list, you will need to specify both term and description.
" However, for a table, bulleted list, or numbered list, you only need to supply an entry for
description.
" A list or table can have as many <item> blocks as needed.
Example:
/// <summary>
/// The GetZero method.
/// <list type="number">
/// <item>
/// <description>Item 1.</description>
/// </item>
/// <item>
/// <description>Item 2.</description>
/// </item>
/// </list>
/// </summary>
public static int GetZero()
{ return 0; }
0
 
LVL 11

Expert Comment

by:bmatumbura
ID: 24225204
Tag: <note>
Type: Inline
Applies To: Can be used inline within any other markup.
Defined By: NDoc, Sandcastle
Syntax: <note type="caution" | "inheritinfo" | "implementnotes">description</note>
Parameters:
type="":
Type of note being displayed
description:
Descriptive text for the note tag
Remarks:
The <note> tag produces a formatted note block.
Example:
/// <summary>
/// <c>Increment</c> method increments the stored number by one.
/// <note type="caution">
/// note description here
/// </note>
/// <preliminary/>
/// </summary>
public void Increment()
{ number++; }
0
 
LVL 11

Expert Comment

by:bmatumbura
ID: 24225211
Tag: <overloads>
Type: Top-Level
Applies To: Property, Method, Event, Operator.
Defined By: NDoc, Sandcastle
Syntax:
Short Form
<overloads>summary_description</overloads>
Expanded Form
<overloads>
<summary>
summary_description
</summary>
[<remarks>remarks_description</remarks>]
[<example>examples_description</example>]
</overloads>
Parameters: None
Remarks:
" The <overloads> tag provides documentation that applies to all the overloads of a member.
" This information will appear on the Overloads topic page for the members.
" This tag only needs to be specified on the first overload.
" The tag can have two forms:
1. In the short form, it includes only one or more text blocks that are treated as the summary.
2. In the expanded form, it can include one or more applicable section tags (summary, remarks
and example).
Examples:
Short Form:
/// <summary>Decrements the number by 1</summary>
/// <overloads>This method has two overloads</overloads>
public void Dec()
{ number--; }
/// <summary>Decrements the number by amount</summary>
/// <param name="amount">The amount to decrement it by</param>
public void Dec( int amount )
{ number -= amount; }
/// <summary>Decrements the number by 1</summary>
/// <overloads>
/// <summary> This method has two overloads</summary>
/// <remarks>remarks description</remarks>
/// <example>code example</example>
/// </overloads>
public void Dec()
{ number--; }
/// <summary> Decrements the amount by number </summary>
/// <param name="amount">The amount to decrement it by</param>
public void Dec( int amount )
{ number -= amount; }
0
 
LVL 11

Expert Comment

by:bmatumbura
ID: 24225223
Tag: <para>
Type: Inline
Applies To: Can be used inline within any other markup.
Defined By: Microsoft, NDoc
Syntax: Microsoft:
<para>content</para>
NDoc:
<para [lang="language"]>content</para>
Parameters:
Microsoft:
content:
The text of the paragraph.
NDoc:
content:
The text of the paragraph.
lang="language"
Applies a filter for this language. (Optional)
Remarks: Microsoft:
" The <para> tag is for use inside a tag, such as <summary>, <remarks>, or <returns>, and lets you
add structure to the text.
" As an alternative, you can use the HTML <p/> or <p></p> tags to create paragraphs.
NDoc:
" This tag is for use inside a tag, such as <summary>, <remarks>, or <returns>, and lets you add
structure to the text.
" A language filter can be attached using the optional lang attribute.
" Standard languages are Visual Basic, C#, C++ and JScript.
" Multiple languages can be specified as a comma separated list such as "Visual Basic, C#, C++".
Microsoft:
/// <summary>
/// Increment method increments the stored number by a specified.
/// <para>
/// This is the first paragraph
/// </para>
/// <para>
/// This is the second paragraph
/// </para>
/// </summary>
public void Increment( int step )
{ number = number + step; }
NDoc:
/// <summary>
/// Increment method increments the stored number by a specified.
/// <para>
/// This is the first paragraph
/// </para>
/// <para lang="C#">
/// This is the second paragraph
/// </para>
/// </summary>
public void Increment( int step )
{ number = number + step; }
0
 
LVL 11

Expert Comment

by:bmatumbura
ID: 24225236
Tag: <param>
Type: Top-Level
Applies To: Property, Method, Event, Operator.
Defined By: Microsoft
Syntax: <param name="name">description</param>
Parameters:
name:
The name of a method parameter.
Enclose the name in double quotation marks (" ").
description:
A description for the parameter.
Remarks:
" The <param> tag should be used in the comment for a method declaration to describe one of the
parameters for the method.
" The text for the <param> tag will be displayed in IntelliSense, the Object Browser, and in the Code
Comment Web Report.
Example:
/// <summary>
/// Increment method increments the stored number by a specified
/// </summary>
/// <param name="step"> specified step</param>
public void Increment( int step )
{ number = number + step; }

0
 
LVL 11

Expert Comment

by:bmatumbura
ID: 24225241
Tag: <paramref>
Type: Inline
Applies To: Can be used inline within any other markup.
Defined By: Microsoft
Syntax: <paramref name="name"/>
Parameters:
name:
The name of the parameter to refer to. Enclose the name in double quotation marks (" ").
Remarks:
" The <paramref> tag gives you a way to indicate that a word in the code comments, for example in a
<summary> or <remarks> block refers to a parameter.
" The XML file can be processed to format this word in some distinct way, such as with a bold or italic
font.
Example:
/// <summary>
/// Increment method increments the stored number by a specified
/// <paramref name="step"/>.
/// </summary>
/// <param name="step"> specified step</param>
public void Increment( int step )
{ number = number + step; }
0
 
LVL 11

Expert Comment

by:bmatumbura
ID: 24225251
Tag: <permission>
Type: Top-Level
Applies To: All Members.
Defined By: Microsoft
Syntax: <permission cref="member">description</permission>
Parameters:
cref="member":
" A reference to a member or field that is available to be called from the current compilation
environment.
" The compiler checks that the given code element exists and translates member to the
canonical element name in the output XML.
" member must appear within double quotation marks (" ").
description:
A description of the access to the member.
Remarks:
" The <permission> tag lets you document the access of a member.
" The PermissionSet class lets you specify access to a member
Example:
/// <summary>
/// Increment method increments the stored number by a specified
/// </summary>
/// <permission cref="System.Security.PermissionSet">
/// Everyone can access this method.
/// </permission>
public void Increment( int step )
{ number = number + step; }
0
 
LVL 11

Expert Comment

by:bmatumbura
ID: 24225256
Tag: <preliminary>
Type: Top-Level
Applies To: All Types and Members.
Defined By: NDoc / Sandcastle
Syntax: <preliminary>[description]</preliminary>
Parameters:
description
An optional textual message or warning that replaces the default preliminary warning.
Remarks:
" The <preliminary> tag marks the documentation for the current item as preliminary.
" If the empty form of this tag is used (<preliminary/>) the default message of
"[This is preliminary documentation and subject to change.]"
will be included in the generated help topic.
" If a value is supplied for the content of this tag, that value will appear in the help topic, replacing the
default message.
" You can format the message text using the para and list tags, but this is not required.
Sandcastle Help File Builder/NDoc:
" Entire help titles can be marked preliminary using the Preliminary documenter/project setting.
Example:
// The class summary will get the default message
/// <preliminary/>
public class MyClass
{
/// <preliminary>
/// <para>
/// This method is just for testing right now.
/// It might be removed in the near future
/// </para>
/// </preliminary>
public void Dump ()
{
// Code for Dump goes here
}
}
0
 
LVL 11

Expert Comment

by:bmatumbura
ID: 24225267
Tag: <remarks>
Type: Top-Level
Applies To: All Types and Members.
Defined By: Microsoft
Syntax: <remarks>description</remarks>
Parameters:
description:
A description of the member.
Remarks:
" The <remarks> tag is used to add information about a type, supplementing the information specified
with <summary>.
" This information is displayed in the Visual Studio Object Browser.
Example:
/// <summary>
/// Increment method increments the stored number by a specified step.
/// </summary>
/// <remarks>
/// You may have some additional information about this class.
/// </remarks>
public void Increment(int step)
{ number = number + step; }
0
 
LVL 11

Expert Comment

by:bmatumbura
ID: 24225275
Tag: <returns>
Type: Top-Level
Applies To: Method.
Defined By: Microsoft
Syntax: <returns>description</returns>
Parameters:
description:
A description of the return value.
Remarks:
" The <returns> tag should be used in the comment for a method declaration to describe the return
value.
" This information is displayed in the Visual Studio Object Browser.
Example:
/// <summary>
/// Increment method increments the stored number by a specified step.
/// </summary>
/// <returns>Returns nothing</returns>
public void Increment(int step)
{ number = number + step; }
0
 
LVL 11

Expert Comment

by:bmatumbura
ID: 24225285
Tag: <see>
Type: Top-Level (Microsoft) or Inline (NDoc/Sandcastle)
Applies To: Can be used inline within any other markup.
Defined By: Microsoft, NDoc, Sandcastle
Syntax: Microsoft:
<see cref="member"/>
NDoc/Sandcastle:
<see cref="member">[label]</see>
OR
<see langword="null | sealed | static | abstract | virtual | true | false|other_key_word"/>
NDoc Only:
<see href="URL">[label]</see>
Parameters:
Microsoft:
cref="member":
" A reference to a member or field that is available to be called from the current
compilation environment.
" The compiler checks that the given code element exists and passes member to the
element name in the output XML.
" Place member within double quotation marks (" ").
NDoc Only:
href = "URL":
A reference to a Top-Level resource at the address given by the URL.
NDoc / Sandcastle:
label:
text to display as the link
langword:
" A common .NET language keyword.
" These keywords are highlighted, and, in some cases, expanded into descriptive phrases
(see remarks for further details).
" Note that although the syntax above only shows the common keywords, any word
specified will be highlighted.
Microsoft:
" The <see> tag lets you specify a link from within text.
" Use <seealso> to indicate that text should be placed in a See Also section.
NDoc:
" Use <seealso> to indicate text that you might want to appear in a See Also section.
" Note: As of release 1.3, the MSDN and VS.NET documenters will only create a link on the first
occurrence of each unique cref specified within a documentation section; further <see> tags will
just be highlighted.
" This improves the readability of the documentation.
langword keyword expansions
null null reference (Nothing in Visual Basic)
sealed sealed (NotInheritable in Visual Basic)
static static (Shared in Visual Basic)
abstract abstract (MustInherit in Visual Basic)
virtual virtual (CanOverride in Visual Basic)
Note: Microsoft defines the <see> tag as both a Top-Level and an Inline tag, while NDoc and Sandcastle
define it as an Inline tag.
Note: While not documented as a Top-Level tag, both Sandcastle and NDoc support the <see> tag as a
Top-Level tag.
Example:
Microsoft:
Top-Level tag:
class Class1
{
/// <summary>
/// Summary of information about this class.
/// </summary>
/// <see cref=System.String/>
public string GetString()
{
// Code for GetString goes here
}
}
Inline tag:
/// <summary>
/// Summary of information about this class
/// See <see cref="System.String"/>
/// for more information about the string class
/// </summary>
public string GetString()
{
// Code for GetString goes here }
}
0
 
LVL 11

Expert Comment

by:bmatumbura
ID: 24225301
Tag: <seealso>
Type: Top-Level (Microsoft) or Inline (NDoc/Sandcastle)
Applies To: All Types and Members.
Defined By: Microsoft, NDoc, Sandcastle
Syntax: Microsoft:
<seealso cref="member"/>
NDoc/Sandcastle:
<seealso cref="member">[label]</seealso>
NDoc Only:
<seealso href="URL">[label]</seealso>
Parameters:
Microsoft:
cref="member":
" A reference to a member or field that is available to be called from the current
compilation environment.
" The compiler checks that the given code element exists and passes member to the
element name in the output XML.
" member must appear within double quotation marks (" ").
NDoc/Sandcastle:
label: text to display as the link
cref = "member":
" A reference to a member or field that is available to be called from the current
compilation environment.
" The compiler checks that the given code element exists and passes member to the
element name in the output XML.
" member must appear within double quotation marks (" ").
NDoc:
href = "URL":
A reference to a Top-Level resource at the address given by the URL.
Remarks:
Microsoft:
" The <seealso> tag lets you specify the text that you might want to appear in a See Also section.
" Use <see> to specify a link from within text.
NDoc:
" Use <see> to specify a link from within text.
" Do not include this tag in the <remarks> section.
Note: Microsoft defines the <seealso> tag as both a Top-Level and an Inline tag, while NDoc and
Sandcastle define it as an Inline tag.
Note: While not documented as a Top-Level tag, both Sandcastle and NDoc support the <seealso> tag
as a Top-Level tag.
Examples:
Microsoft:
Top-Level tag:
/// <summary>
/// You may have some primary information about this class.
/// </summary>
/// <seealso cref="System.String"/>
public string GetString()
{
// Code for GetString goes here
}
Inline tag:
/// <summary>
/// You may have some primary information about this class.
/// See <seealso cref="System.String"/>
/// for information about the string class
/// </summary>
public string GetString()
{
// Code for GetString goes here
}
NDoc/Sandcastle:
Inline tag (cref):
/// <summary>
/// You may have some primary information about this class.
/// See <seealso cref="System.String"/>
/// for information about the string class
/// </summary>
public string GetString()
{
// Code for GetString goes here
}
Inline tag (href, NDoc only):
/// <summary>
/// You may have some primary information about this class.
/// See < seealso href="http://www.someurl.com"/>
/// for information about the string class
/// </summary>
public string GetString()
{
// Code for GetString goes here
}
0
 
LVL 11

Expert Comment

by:bmatumbura
ID: 24225322
Tag: <summary>
Type: Top-Level
Applies To: All Types and Members.
Defined By: Microsoft
Syntax: <summary>description</summary>
Parameters:
description:
A summary of the object.
Remarks:
" The <summary> tag should be used to describe a type or a type member.
" Use <remarks> to add supplemental information to a type description.
" The text for the <summary> tag is the only source of information about the type in IntelliSense, and
is also displayed in the Object Browser.
Example:
/// <summary>
/// Gets or sets a
/// <see cref="T:System.Windows.Media.Brush"/>
/// used to fill the area between the borders of a
/// <see cref="T:System.Windows.Controls.InkCanvas"/>
/// see <see langword="null"/> as reference
/// </summary>
public int MyProp
{
get { return _myProp; }
set { _myProp = value; }
}
0
 
LVL 11

Expert Comment

by:bmatumbura
ID: 24225331
Tag: <threadsafety>
Type: Top-Level
Applies To: Class, Structure.
Defined By: NDoc, Sandcastle
Syntax: <threadsafety static="true|false" instance="true|false"/>
Parameters:
static="true|false"
Indicates whether static members of this class are safe for multi-threaded operations.
instance="true|false"
Indicates whether members of instances of this type are safe for multi-threaded operations.
Remarks:
The <threadsafety> tag is used to describe how a class or structure behaves in multi-threaded scenarios.
Example:
/// <threadsafety static="true" instance="false"/>
public class MyClass
{
/// not safe across threads
public void InstanceMethod()
{
// Code for instanceMethod goes here
}
/// safe across threads
public static void StaticMethod()
{
// Code for StaticMethod goes here
}
}
0
 
LVL 11

Expert Comment

by:bmatumbura
ID: 24225350
Tag: <typeparam>
Type: Top-Level
Applies To: Method (Generic)
Defined By: Microsoft
Syntax: <typeparam name="name">description</typeparam>
Parameters:
name:
The name of the type parameter.
Enclose the name in double quotation marks (" ").
description:
A description for the type parameter.
Remarks:
" The <typeparam> tag should be used in the comment for a generic type or method declaration to
describe a type parameter.
" Add a tag for each type parameter of the generic type or method.
" For more information, see Generics (C# Programming Guide).
" The text for the <typeparam> tag will be displayed in IntelliSense, the Object Browser code
comment web report.
Example:
/// comment for class
public class TestClass
{
/// <summary>
/// Creates a new array of arbitrary type <typeparamref name="T"/>
/// </summary>
/// <typeparam name="T">The element type of the array</typeparam>
public static T[] mkArray<T>( int n )
{
return new T[n];
}
}
0
 
LVL 11

Expert Comment

by:bmatumbura
ID: 24225358
Tag: <typeparamref>
Type: Inline
Applies To: Inline within any other markup, for Generic methods
Defined By: Microsoft
Syntax: <typeparamref name="name"/>
Parameters:
name:
The name of the type parameter.
Enclose the name in double quotation marks (" ").
Remarks:
" For more information on type parameters in generic types and methods, see Generics.
" Use this tag to enable consumers of the documentation file to format the word in some distinct way,
for example in italics.
Example:
/// <summary>
/// <para>
/// <typeparam name="T">The element type to swap</typeparam>
/// </para>
/// <para>
/// Swap data of type <typeparamref name="T"/>
/// </para>
/// </summary>
public void Swap<T>( ref T lhs, ref T rhs )
{
T temp;
temp = lhs;
lhs = rhs;
rhs = temp;
}
0
 
LVL 11

Expert Comment

by:bmatumbura
ID: 24225372
Tag: <value>
Type: Top-Level
Applies To: Property
Defined By: Microsoft
Syntax: <value>property-description</value>
Parameters:
property-description:
A description for the property.
Remarks:
" The <value> tag lets you describe the value that a property represents.
" Note that when you add a property via code wizard in the Visual Studio .NET development
environment, it will add a <summary> tag for the new property. You should then manually add a
<value> tag to describe the value that the property represents.
" Visual Studio doesnt use <value>, but rather uses <summary> for IntelliSense.
Example:
/// text for class Employee
public class Employee
{
private string _name;
/// <summary>
/// The Name property represents the employee's name.
/// </summary>
/// <value>
/// The Name property gets/sets the _name data member.
/// </value>
public string Name
{
get {return _name;}
set {_name = value;}
}
}
/// text for class MainClass
public class MainClass
{
/// text for Main
static void Main()
{
// Code for Main goes here
}
}
0
 
LVL 11

Accepted Solution

by:
bmatumbura earned 2000 total points
ID: 24225382
Finally:
Sandcastle Test.cs Example
using System;
using System.Collections.Generic;
using System.Diagnostics.CodeAnalysis;
using System.Runtime.Serialization;
namespace TestNamespace
{
/// <summary>
/// Tests whether sandcastle can handle all c# tags as defined at
/// http://msdn2.microsoft.com/en-us/library/5ast78ax.aspx.
/// Comments of method "Increment (int step)" include almost all tags.
/// Method "Swap" is used to test generics tags, such as "typeparam".
/// <threadsafety static="true" instance="false"/>
/// </summary>
[Serializable()]
public class StoredNumber
{
/// <summary>
/// Initializes the stored number class with a starting value.
/// </summary>
public StoredNumber( int value )
{ number = value; }
private int number;
/// <preliminary>
/// <para>
/// This method is just for testing right now.
/// It might be removed in the near future
/// </para>
/// </preliminary>
public void PreliminaryTest()
{
}
/// <overloads>
/// <summary>
/// test overloads tag
/// </summary>
/// </overloads>
public void Dec()
{ number--; }
/// <summary>
/// dec by a specified step
/// </summary>
/// <param name="step"></param>
public void Dec( int step )
{ number -= step; }
/// <summary>
/// <c>Increment</c> method increments the stored number by one.
/// <note type="caution">
/// note description here
/// </note>
/// <preliminary/>
/// </summary>
public void Increment()
{ number++; }
/// <summary>
/// <c>Increment</c> method increments the stored number by a
/// specified <paramref name="step"/>.
/// <list type="number">
/// <item>
/// <description>Item 1.</description>
/// </item>
/// <item>
/// <description>Item 2.</description>
/// </item>
/// </list>
/// <para>
/// see <see cref="System.Int32"/>
/// </para>
/// <para>
/// seealso <seealso cref="System.Int64"/>
/// </para>
/// </summary>
/// <remarks>
/// You may have some additional information about this class.
/// </remarks>
/// <example>
/// This sample shows how to call the GetZero method.
/// <code>
/// class TestClass
/// {
/// static int Main()
/// { return GetZero(); }
/// }
/// </code>
/// </example>
/// <exception cref="System.Exception">Thrown when...</exception>
/// <param name="step"> specified step</param>
/// <permission cref="System.Security.PermissionSet">
/// Everyone can access this method.
/// </permission>
/// <returns>Returns nothing</returns>
/// <value>The Name property gets/sets the _name data member.</value>
public void Increment( int step )
{ number = number + step; }
/// <summary>
/// <para>
/// <typeparam name="T">The element type to swap</typeparam>
/// </para>
/// <para>
/// Swap data of type <typeparamref name="T"/>
/// </para>
/// </summary>
public void Swap<T>( ref T lhs, ref T rhs )
{
T temp;
temp = lhs;
lhs = rhs;
rhs = temp;
}
/// <summary>Gets the stored number. </summary>
public int Value
{
get { return (number); }
}
private int _myProp;
/// <summary>
/// Gets or sets a
/// <see cref="T:System.Windows.Media.Brush"></see>
/// used to fill the area between the borders of a
/// <see cref="T:System.Windows.Controls.InkCanvas"></see>.
/// see <see langword="null"/> as reference
/// </summary>
public int MyProp
{
get { return _myProp; }
set { _myProp = value; }
}
}
}

Open in new window

0
 

Author Closing Comment

by:dchau12
ID: 31574212
dude - awesome....
0

Featured Post

Concerto Cloud for Software Providers & ISVs

Can Concerto Cloud Services help you focus on evolving your application offerings, while delivering the best cloud experience to your customers? From DevOps to revenue models and customer support, the answer is yes!

Learn how Concerto can help you.

Question has a verified solution.

If you are experiencing a similar issue, please ask a related question

When you’re making plans to join the modern business race, you should analyze various details that may affect your results. Nowadays, millions of businesses are trying to grow into established and appreciated professional enterprises.
Read about why it is more lucrative for an IT company to participate in government projects.
With the power of JIRA, there's an unlimited number of ways you can customize it, use it and benefit from it. With that in mind, there's bound to be things that I wasn't able to cover in this course. With this summary we'll look at some places to go…
Starting up a Project

830 members asked questions and received personalized solutions in the past 7 days.

Join the community of 500,000 technology professionals and ask your questions.

Join & Ask a Question