Page History

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="26abea46-2697-4dff-a11f-a9e7d46adcb3"><ac:plain-text-body><![CDATA[

@author

<author>[value]</author>

No

No

The author tag tends to help who is responsible for a class or method.
]]></ac:plain-text-body></ac:structured-macro>

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="f0a44e27-3450-4256-8afe-cdbc513f45fc"><ac:plain-text-body><![CDATA[

@version

<version>[value]</version>

No

No

The version tag defines the version of the method.

]]></ac:plain-text-body></ac:structured-macro>

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="3ff44758-c910-42f1-a601-6df06afc01cf"><ac:plain-text-body><![CDATA[

@param

<param name="">[desc]</para>

Yes

Yes

Describes a parameter in a method signature. This is often
]]></ac:plain-text-body></ac:structured-macro>
auto-generated by Visual Studio for methods.

<typeparam name="">
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="d870a7da-d1f3-47e9-a41b-cd9e74f86cc2"><ac:plain-text-body><![CDATA[ [desc]
]]></ac:plain-text-body></ac:structured-macro>
</typeparam>

Yes

Yes

Describes a generic type parameter.

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="518a4b07-1e1b-4ef3-a037-03728ca42447"><ac:plain-text-body><![CDATA[

@return

<returns>[desc]</returns>

Yes

Yes

Only for methods that have a return value.  This is a good place to
]]></ac:plain-text-body></ac:structured-macro>
note if the method can return null or not. 

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="93a64fa9-d24e-45ea-8b33-064e1412b5f5"><ac:plain-text-body><![CDATA[

@throws

<exception cref="[Type]">
]]></ac:plain-text-body></ac:structured-macro>
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="22a188ab-df50-429e-8d64-4135fc596aa4"><ac:plain-text-body><![CDATA[ [desc]
]]></ac:plain-text-body></ac:structured-macro>
</exception>

No

Yes

This denotes when a class method or property can throw an exception
and the exception type that it throws. The description will tell the case
of why an exception is thrown if its not obvious.

@exception

<exception cref="">
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="b0374c0d-1378-4801-89a5-035c85f639fc"><ac:plain-text-body><![CDATA[ [desc]
]]></ac:plain-text-body></ac:structured-macro>
</exception>

No

Yes

Same as above

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="5873acb5-2278-4251-801f-d3d5e6b3a906"><ac:plain-text-body><![CDATA[

<value>[desc]</value>

Yes

Yes

Describes what the property [value] represents.

]]></ac:plain-text-body></ac:structured-macro>

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="5932b7f3-29e3-4a71-918b-bfd2d7441888"><ac:plain-text-body><![CDATA[

<permission cref="[Member]" />

No

Yes

Notes the access level of a type or member. 

]]></ac:plain-text-body></ac:structured-macro>

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="d37183a6-231b-4b8f-8964-1275ec9918db"><ac:plain-text-body><![CDATA[

@see

<seealso cref="[Member]" />

No

Yes

This links documentation that would beneficial in viewing in the relation
]]></ac:plain-text-body></ac:structured-macro>
to the current documentation. This is placed in the "See Also" section
at the bottom of the page.

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="4b6fb88a-3e8e-4fdd-8837-22a0e9a86d4a"><ac:plain-text-body><![CDATA[

{@link ref}

<see cref="[Member]" />

Yes

Yes

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="4854276f-75ff-40a4-9181-9e49e5da2a2d"><ac:plain-text-body><![CDATA[

{@link ref}

<paramref name="[Member]" />

Yes

Yes

Inline element that references a parameter of the method, typically
]]></ac:plain-text-body></ac:structured-macro>
used inside of the remarks or summary section.

{@link ref}

<typeparamref
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="63dc632f-28d1-4f08-a7f8-9ba55d45b967"><ac:plain-text-body><![CDATA[        name="[Member]" />

Yes

Yes

Inline element that references a generic type parameter of the method,
]]></ac:plain-text-body></ac:structured-macro>
typically used inside of the remarks or summary section.

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="9aeedcf6-c0e9-4c43-bfdd-d24feb35f6a1"><ac:plain-text-body><![CDATA[

@since

<since>[value]</since>

No

No

This describes that this functionality was supported starting in version x.

]]></ac:plain-text-body></ac:structured-macro>

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="ed7fefa8-7381-4467-b6fd-41fd9cde9824"><ac:plain-text-body><![CDATA[

@serial

No

Unsure

[Serializable] - Sandcastle could use the [Serializable] attribute to
]]></ac:plain-text-body></ac:structured-macro>
denote this in the generated documentation, but this needs to
be confirmed.

@deprecated
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="6fee916d-3626-404f-bde3-208fbda17ee9"><ac:plain-text-body><![CDATA[

No

Yes

[Obsolete] - Sandcastle / SHFB does make use of the [Obsolete]
]]></ac:plain-text-body></ac:structured-macro>
attribute to note that method is deprecated in the generated
docs.

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="248989d9-61f0-4e90-a03d-281c4473a419"><ac:plain-text-body><![CDATA[

<summary>[desc]<summary>

Yes

Yes

Give a brief overview about a class, namespace or member does
]]></ac:plain-text-body></ac:structured-macro>
in the code. Intellisense will pick up summary and use it inside of
Visual Studio.  Be concise.

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="75731e6b-a627-4b9e-9a4c-72f62c63dcb9"><ac:plain-text-body><![CDATA[

<remarks>[xml]</remarks>

Yes

Yes

Give the full explanation of what class, namespace or member does
]]></ac:plain-text-body></ac:structured-macro>
in the code. This typically should include code examples.

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="cba2e03c-aec8-4af9-abf3-c8ac226d036d"><ac:plain-text-body><![CDATA[

<example>[xml]</example>

No

Yes

Denotes a full section targeted towards providing an example in the
]]></ac:plain-text-body></ac:structured-macro>
generated docs. 

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="9a9b3730-a29a-49ad-a60e-c0c0001c2bba"><ac:plain-text-body><![CDATA[

[<p />]

<para>[text]</para>

Yes

Yes

This should always be used for paragraphs inside of the <remarks />
]]></ac:plain-text-body></ac:structured-macro>
section.  In Javadocs <p> is often used as line break and it does not
wrap the paragraph.  In the xml, it needs to wrap the paragraph text.

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="78ca85e2-4212-43a2-9c26-ac29633cd1f3"><ac:plain-text-body><![CDATA[

<code />

<c>[Type|value]</c>

Yes

Yes

@version

<version>[value]</version>

No

No

The version tag defines the version of the method.

@param

<param name="">[desc]</para>

Yes

Yes

Describes a parameter in a method signature. This is often
auto-generated by Visual Studio for methods.

<typeparam name="">
[desc]
</typeparam>

Yes

Yes

Describes a generic type parameter.

@return

<returns>[desc]</returns>

Yes

Yes

Only for methods that have a return value.  This is a good place to
note if the method can return null or not. 

@throws

<exception cref="[Type]">
[desc]
</exception>

No

Yes

This denotes when a class method or property can throw an exception
and the exception type that it throws. The description will tell the case
of why an exception is thrown if its not obvious.

@exception

<exception cref="">
[desc]
</exception>

No

Yes

Same as above

<value>[desc]</value>

Yes

Yes

Describes what the property [value] represents.

<permission cref="[Member]" />

No

Yes

Notes the access level of a type or member. 

@see

<seealso cref="[Member]" />

No

Yes

This links documentation that would beneficial in viewing in the relation
to the current documentation. This is placed in the "See Also" section
at the bottom of the page.

{@link ref}

<see cref="[Member]" />

Yes

Yes

This will create a link for the specified member. The cref part of this
can become tricky, especially with overloaded methods and generics.

In JavaDoc the sharp (#) prefix denotes a member, i.e.
{@link #methodName(Class,TokenStream)}      In .Net, this would
be <see cref="ClassName.MethodName(Type, TokenStream)" />

{@link ref}

<paramref name="[Member]" />

Yes

Yes

Inline element that references a parameter of the method, typically
used inside of the remarks or summary section.

{@link ref}

<typeparamref
       name="[Member]" />

Yes

Yes

Inline element that references a generic type parameter of the method,
typically used inside of the remarks or summary section.

@since

<since>[value]</since>

No

No

This describes that this functionality was supported starting in version x.

@serial

No

Unsure

[Serializable] - Sandcastle could use the [Serializable] attribute to
denote this in the generated documentation, but this needs to
be confirmed.

@deprecated

No

Yes

[Obsolete] - Sandcastle / SHFB does make use of the [Obsolete]
attribute to note that method is deprecated in the generated
docs.

<summary>[desc]<summary>

Yes

Yes

Give a brief overview about a class, namespace or member does
in the code. Intellisense will pick up summary and use it inside of
Visual Studio.  Be concise.

<remarks>[xml]</remarks>

Yes

Yes

Give the full explanation of what class, namespace or member does
in the code. This typically should include code examples.

<example>[xml]</example>

No

Yes

Denotes a full section targeted towards providing an example in the
generated docs. 

[<p />]

<para>[text]</para>

Yes

Yes

This should always be used for paragraphs inside of the <remarks />
section.  In Javadocs <p> is often used as line break and it does not
wrap the paragraph.  In the xml, it needs to wrap the paragraph text.

<code />

<c>[Type|value]</c>

Yes

Yes

Instructs Sandcastle to format the text as code.  examples: <c>null</c>,
<c>true</c>, <c>TokenStream</c>, <c>string</c>

JavaDocs will often wrap this inside of <code /> tags. This will cause
formatting issues if its carried over to the .NET comments.
Sandcastle will attempt to render as a code example.   

<code />

<code lang="[lang]">
[example]
</code>

No

Yes

This element specifies a code example. 

SHFP supports the lang attribute, so it would be wise to denote which
language the code example is in. 

<ul>,<ol>

<list>

Yes

Yes

When creating a list, you should use the <list> element. However SHFB
will let <ul> and <ol> elements be used in the generated docs.

<li>

<item>

Yes

Yes

When creating a list item, you should use the <item> element.
SHFP will let <li> be used in the generated docs.

<include file="[filepath]"

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="27035c5d-cb24-4698-9a2b-385d75dcb50c"><ac:plain-text-body><![CDATA[

<code />

<code lang="[lang]">
]]></ac:plain-text-body></ac:structured-macro>
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="b6fa6386-e293-4f94-b825-effb0f0a877e"><ac:plain-text-body><![CDATA[ [example]
]]></ac:plain-text-body></ac:structured-macro>
</code>

No

Yes

<ul>,<ol>

<list>

Yes

Yes

When creating a list, you should use the <list> element. However SHFB
will let <ul> and <ol> elements be used in the generated docs.

<li>

<item>

Yes

Yes

When creating a list item, you should use the <item> element.
SHFP will let <li> be used in the generated docs.

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="98672b96-31bb-40f2-a1ad-59d8c0cc45f3"><ac:plain-text-body><![CDATA[

<include file="[filepath]"
]]></ac:plain-text-body></ac:structured-macro>
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="b5e52bc9-b427-461c-b3dc-0b72710112ed"><ac:plain-text-body><![CDATA[    path="tagpath[@name=id]" />

No

Yes

This element will let you include documentation from another file and
]]></ac:plain-text-body></ac:structured-macro>from another file and
tag. The "path" attribute is the xpath query to the member you wish to
link.  This an alternative to putting the documentation inside the code.
It can also be more complicated.
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="3ee2790b-a58d-42dd-b396-eeef6758f206"><ac:plain-text-body><![CDATA[
link.  This an alternative to putting the documentation inside the code.

It can also be more complicated.

<note>[xml|text]</note>

No

Yes

Nonstandard. This tag is supported by SHFB and possibly even
]]></ac:plain-text-body></ac:structured-macro>
Sandcastle. This was an NDoc tag that was requested heavily.

This creates a note block inside the generated docs.

<inheritdoc />

No

Yes

Nonstandard. This tag is supported by SHFB. This will specify SHFB
to use documentation from the inherited member documentation.