Question about comment format.

  • Thread starter Thread starter news.microsoft.net
  • Start date Start date
N

news.microsoft.net

When I wrote <summary> comment for a function. I wrote:
/// <summary>
/// Line one.
/// Line two.
/// </summary>
I want the intelligence mechanism display:
Line one.
Line Two.
but it display:
Line one. Line two.
They were put in one line. How could I get what I want? Thank you.
 
When I wrote <summary> comment for a function. I wrote:
/// <summary>
/// Line one.
/// Line two.
/// </summary>
I want the intelligence mechanism display:
Line one.
Line Two.
but it display:
Line one. Line two.
They were put in one line. How could I get what I want? Thank you.
Click to expand...

I'm not sure about this, but you could try to include Escape Sequenzes (\n
\r\t,...) or maybe encoded HTML Tags (&lt;br&gt;... ).

Depends on what MS used for rendering the intellisense

--
------ooo---OOO---ooo------

Peter Koen - www.kema.at
MCAD CAI/RS CASE/RS IAT

------ooo---OOO---ooo------
 
news.microsoft.net said:
When I wrote <summary> comment for a function. I wrote:
/// <summary>
/// Line one.
/// Line two.
/// </summary>
I want the intelligence mechanism display:
Line one.
Line Two.
but it display:
Line one. Line two.
They were put in one line. How could I get what I want? Thank you.
Click to expand...

You can break them into paragraphs using:

/// <summary>
/// <para>Paragraph 1</para>
/// <para>Paragraph 2</para>
/// <summary>

Or you could use <list> if that's more appropriate.

See "XML documentation, tags for comments" in MSDN for more
information.
 
I have tried <para>, <p>, <list> and even <br> and \r \n.
They do not take any effect. (<list> inserts some white space but does not
insert CRLF)
It seems that vs.net does not know their meanings.
What can I do then?
Thank you.
 
news.microsoft.net said:
I have tried <para>, <p>, <list> and even <br> and \r \n.
They do not take any effect. (<list> inserts some white space but does not
insert CRLF) It seems that vs.net does not know their meanings.
What can I do then?
Click to expand...

Where are you looking for the effects? Are you building the
documentation with NDoc, or just looking at what VS.NET shows in
tooltips?
 
I suspect that the IDE attempts to keep your summaries compact so that
intellisense windows do not grow to large. Documentation generators should
get the output right, but VS doesn't appear to do this properly Ideally you
would want the summary tag to be rather short, with more complex comments in
the <remarks> tag.
 
news.microsoft.net said:
I have tried <para>, <p>, <list> and even <br> and \r \n.
They do not take any effect. (<list> inserts some white space but does not
insert CRLF)
It seems that vs.net does not know their meanings.
Click to expand...

I suspect you are using "Build Comments Web Pages". To achieve line and
paragraph breaks you will need to use the XML tag <newpara/> and the HTML
tag <br> in your comments. Unfortunately <br> is not well formed XML and VS
will complain abot it. So you will need to turn off the error CS1570 in
your project settings.

See:
http://msdn.microsoft.com/library/d...n-us/cscomp/html/vcerrcompilererrorsc1570.asp

-- Alan
 
Hi Alan,
tag <br> in your comments. Unfortunately <br> is not well formed XML and VS
will complain abot it. So you will need to turn off the error CS1570 in
your project settings
Click to expand...

There is no need to do so, just replace <br> with <br/>. ;-)
 
Kefroth said:
There is no need to do so, just replace <br> with <br/>. ;-)
Click to expand...

But then in the comments web pages you don't get a break. At least you
didn't at one time. I haven't tried it lately.

-- Alan
 
I just want vs.net tooltip text to be shown in this format:
This is a summary text.
This is another summary text.
 
You can break them into paragraphs using:
/// <summary>
/// <para>Paragraph 1</para>
/// <para>Paragraph 2</para>
/// <summary>

Or you could use <list> if that's more appropriate.

See "XML documentation, tags for comments" in MSDN for more
information.
Click to expand...


Yea... this still does not work with Intellisense, however, Jon. It works great
with NDoc, but if you are using the object browser or intellisense, it displays
anything in the <para></para> tags as one long run-on sentence from the
<summary></summary> tags.
 
Kerry Sanders said:
Yea... this still does not work with Intellisense, however, Jon. It works great
with NDoc, but if you are using the object browser or intellisense, it displays
anything in the <para></para> tags as one long run-on sentence from the
<summary></summary> tags.
Click to expand...

Unfortunately this sounds like a limitation in VS.NET then :(
 
Unfortunately this sounds like a limitation in VS.NET then :(
Click to expand...


Yes. The option to create documentation web pages is severely broken, IMHO. It
runs everything together in one long sentence. It does not handle any of the
tags such as <para> or <remarks>.

I found NDoc and never looked back. It is very cool. Now if I could just
figure out how to use the Visual Studio Help Integration tool and integrate my
help file into the IDE. :)
 
Back
Top