468,317 Members | 1,589 Online
Bytes | Developer Community
New Post

Home Posts Topics Members FAQ

Post your question to a community of 468,317 developers. It's quick & easy.

/// <example>

Where will code that is preceded with:

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

actually show up?

I can see my <summaryand <remarkscode showing up in the code comment
pages and in the Object Browser, but where will the example come into play?
Sep 21 '06 #1
8 1557
On Wed, 20 Sep 2006 21:36:32 -0400, Scott M. wrote:
Where will code that is preceded with:

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

actually show up?

I can see my <summaryand <remarkscode 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.
--
Tom Porterfield
Sep 21 '06 #2
Ok, but is there no use for it in VS.NET?
"Tom Porterfield" <tp******@mvps.orgwrote in message
news:15****************@tpportermvps.org...
On Wed, 20 Sep 2006 21:36:32 -0400, Scott M. wrote:
>Where will code that is preceded with:

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

actually show up?

I can see my <summaryand <remarkscode 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.
--
Tom Porterfield

Sep 21 '06 #3
"Scott M." <No****@NoSpam.coma écrit dans le message de news:
er**************@TK2MSFTNGP05.phx.gbl...

| 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

--
Joanna Carter [TeamB]
Consultant Software Engineer
Sep 21 '06 #4
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 <exampletag
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.

--
Peter Macej
Helixoft - http://www.helixoft.com
VSdocman - Commenter and generator of class documentation for C#, VB
..NET and ASP .NET code
Sep 21 '06 #5
Yes, but my question was not about <typeparam>, it was about <example>.
"Joanna Carter [TeamB]" <jo****@not.for.spamwrote in message
news:uo**************@TK2MSFTNGP03.phx.gbl...
"Scott M." <No****@NoSpam.coma écrit dans le message de news:
er**************@TK2MSFTNGP05.phx.gbl...

| 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

--
Joanna Carter [TeamB]
Consultant Software Engineer


Sep 21 '06 #6
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" <pe***@helixoft.comwrote in message
news:%2****************@TK2MSFTNGP03.phx.gbl...
>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 <exampletag
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.

--
Peter Macej
Helixoft - http://www.helixoft.com
VSdocman - Commenter and generator of class documentation for C#, VB .NET
and ASP .NET code

Sep 21 '06 #7
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 <exampletag 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.

--
Peter Macej
Helixoft - http://www.helixoft.com
VSdocman - Commenter and generator of class documentation for C#, VB
..NET and ASP .NET code
Sep 22 '06 #8
Thanks, but you missed the point of my question. I wanted to know what
<examplebuys 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.
"Peter Macej" <pe***@helixoft.comwrote in message
news:O$**************@TK2MSFTNGP05.phx.gbl...
>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 <exampletag 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.

--
Peter Macej
Helixoft - http://www.helixoft.com
VSdocman - Commenter and generator of class documentation for C#, VB .NET
and ASP .NET code

Sep 22 '06 #9

This discussion thread is closed

Replies have been disabled for this discussion.

Similar topics

9 posts views Thread by Francesco Moi | last post: by
1 post views Thread by Christian Schmidbauer | last post: by
4 posts views Thread by higabe | last post: by
129 posts views Thread by Torbjørn Pettersen | last post: by
8 posts views Thread by Michael | last post: by
11 posts views Thread by Les Paul | last post: by
3 posts views Thread by Jesper Odgaard | last post: by
1 post views Thread by John Mark Howell | last post: by
reply views Thread by NPC403 | last post: by
1 post views Thread by howard w | last post: by
By using this site, you agree to our Privacy Policy and Terms of Use.