/// <example>

[Scott M.]

Where will code that is preceded with:

/// <example>
/// some comments
/// </example>

actually show up?

I can see my <summary> and <remarks> code showing up in the code comment
pages and in the Object Browser, but where will the example come into play?

 

[Tom Porterfield]

Where will code that is preceded with:

/// <example>
/// some comments
/// </example>

actually show up?

I can see my <summary> and <remarks> code showing up in the code comment
pages and in the Object Browser, but where will the example come into play?

Document generation tools such as NDoc will include data there in the help
files that they generate. See
http://ndoc.sourceforge.net/content/tag_example.htm for an example.

 

[Scott M.]

Ok, but is there no use for it in VS.NET?

Document generation tools such as NDoc will include data there in the help
files that they generate. See
http://ndoc.sourceforge.net/content/tag_example.htm for an example.

 

[Joanna Carter [TeamB]]

"Scott M." <[email protected]> a écrit dans le message de (e-mail address removed)...

| Ok, but is there no use for it in VS.NET?

/// <summary>
/// generic property class
/// </summary>
/// <typeparam name="valueT">the type of the value held in the
Property</typeparam>
public class Property<valueT>
{
...
}

The above comment shows a code insight hint showing the typeparam text, when
typing Property<... into a field or other member.

Joanna

 

[Peter Macej]

Ok, but is there no use for it in VS.NET?

Not directly. AFAIK, VS .NET only uses the following tags in
IntelliSense or Object Browser:
<summary>
<param>
<typeparam>
<returns>
<value>

Other tags are used for generating documentation. The <example> tag
creates Example section in generated documentation, as you can see for
example at http://tinyurl.com/mazqb. So there is indirect use of it if
you generate documentation. User then can point to the function, press
F1 and get descriptive help topic including example.

 

[Scott M.]

Yes, but my question was not about <typeparam>, it was about <example>.

 

[Scott M.]

Well, actually it does not create anything in the code comment pages
generated by VS.NET. Summary and Remarks will show up there, but not
description.

FYI, the link you provided redirects to
http://msdn2.microsoft.com/en-us/library/t97s7bs3.aspx, which an article
about the String.Trim() method.

 

[Peter Macej]

Well, actually it does not create anything in the code comment pages

generated by VS.NET. Summary and Remarks will show up there, but not
description.

VS .NET cannot generate MSDN like documentation. You need to use some
tool for this, for example our VSdocman.

FYI, the link you provided redirects to
http://msdn2.microsoft.com/en-us/library/t97s7bs3.aspx, which an article
about the String.Trim() method.

That's correct. I posted this link as random example of how it looks
like. This article contains "Example" section with the code showing how
to use it. When you use Trim method in your code and press F1, you'll
get this MSDN topic.

If you use <example> tag in your own method, you can do the same. You
can generate MSDN documentation for it (using 3rd party tool) which will
contain "Example" section with your code samples.

If you have for example property prop1 with the following comment (not
complete here):
/// <summary>Our sample property.</summary>
/// <remarks>
/// This property is really interesting.
/// </remarks>
/// <value>Some nice text.</value>
/// <example>This is an example how to use it:
/// <para></para>
/// <code>try
/// {
/// if (this.prop1 != @&quot;hello&quot
/// {
/// return SampleEnum.value2;
/// }
/// else
/// {
/// return SampleEnum.value3;
/// }
/// }
/// catch (Exception ex)
/// {
/// return SampleEnum.value1;
/// }</code></example>
/// <author>Peter Macej</author>
/// <version>2.0</version>
/// <revision>27</revision>
/// <copyright>(c) 2006 Helixoft</copyright>
/// <todo>Improve exception handling</todo>
/// <seealso cref="TestDLL.DllClass1.prop2">
/// Another property
/// </seealso>
public string prop1

then our VSdocman generates the help page for it available at
http://tinyurl.com/r86vf.

 

[Scott M.]

Thanks, but you missed the point of my question. I wanted to know what
<example> buys me in VS.NET (not a 3rd party documentation tool). You
replied that it helps with generated documentation. The only generated
documentation in VS.NET is Code Comment Pages.