Sandcastle November CTP - Issues with some xml tags.
Hello All,
I have just been testing the November Sandcastle CTP and I have noticed a few small issues regarding some of the xml tags. I have created a simple class which I have included which demonstrates these issues. When I compile this code and build a v2.0 .HXS help file using either the Prototype or VS2005 presentation type, these are the following issues I have noticed in the example ExampleMethod() method and are reproducible using the code example I an included:
- 1) The caption of my <seealso> tag does not appear.
- 2) In the <example> tag, the <see cref="Object"/> works, but the <see cref="ExampleMethod"/> does not.
- 3) When using the <c> tag, the text within it appears in a slightly different font, but it is not highlighted as I would have expected. I have a <c>true<c> in the example code, but although the word true appears it does not particular stand-out from the other text.
- 4) When building for the VS2005 presentation style, it not longer displays the text indicating where an inherited member has been inherited
from. For example, the Equals method is inherited from the Object class and when you compile the help file to the Prototype presentation you
see the text (Inherited from Object.) for the Equal method, but then you compile for the VS2005 presentation style you do not.using System;
using System.Collections.Generic;
using System.Text;namespace XmlTagsDemo
{
/// <summary>
/// Represents a class to demonstrate issues when generating documentation.
/// </summary>
public class XmlTagsDemo1
{
/// <summary>
/// Initializes a new instance of the <see cref="XmlTagsDemo1"/> class.
/// </summary>
public XmlTagsDemo1()
{
}/// <summary>
/// A example method to test if xml tags appear in generated documentation for <see cref="XmlTagsDemo1"/>.
/// </summary>
/// <param name="a">A.</param>
/// <param name="multiplyByFour"> This should be <c>true</c> if you want it multiplied by 4.</param>
/// <returns>The argument multiplied by either 2 or 4.</returns>
/// <example>
/// This example is about this <see cref="ExampleMethod"/> method, but the reference I have put in the example which
/// refers to the same method does not work.
/// The following reference to the <see cref="Object"/> does work.
/// </example>
/// <seealso cref="System.Data.DataColumn.Expression"> This caption should appear but does not!.</seealso>
public int ExampleMethod(int a, bool multiplyByFour)
{
return a * ( multiplyByFour ? 4 : 2 );
}
}
}
Answers
We will provide a fix for this in our December CTP.
Anand.
All Replies
- Another small point I have noticed is that when it is compiled for the VS2005 presentation style, the code in the <example> tag does not appear in a light blue colour like it does when compiled for the prototype presentation style.
MCJ,
Item 1: It’s not clear anywhere whether the caption/description needs to appear and if so where it needs to appear. Eg: /// <seealso cref="System.Data.DataColumn.Expression"> This caption should appear but does not!.</seealso>
Right now we just show the value of cref attribute i.e. “System.Data.DataColumn.Expression” but not the description i.e. “This caption should appear but does not!”. This is as per the usage described at http://msdn2.microsoft.com/en-gb/library/xhd7ehkk(VS.80).aspx
Item 3: Not sure of what style/font-size/color needs to be applied for <c> tags. You say highlighted so does this means to have them as bold?
Anand..
Hello Anand,
Thank you for looking into these items. I have some more information on the two items you highlighted:
Item 1: In the usage described in http://msdn2.microsoft.com/en-gb/library/xhd7ehkk(VS.80).aspx, you will see in the remarks section it states "The <seealso> tag lets you specify the text that you might want to appear in a See Also section". This is what does not currently appear to work.
In the example I have given, all I see in the See Also section is Expression which I can click on which takes me to the help for System.Data.DataColumn.Expression. Because I have specified a caption, this should appear instead of the word Expression and allow me to click on it. In the http://msdn2.microsoft.com/en-gb/library/xhd7ehkk(VS.80).aspx help, it does say you can specify a text that will appear, and indeed, on the same page you will see the See Also section that makes use of this feature.
Another example of this problem is illustrated here:
/// <seealso cref="System.Data.DataColumn.Expression"> for examples of filter expressions.</seealso>
/// <seealso cref="System.Data.DataTable.Select(String)"> for a method that uses a filter expression.</seealso>
When the above two lines are compiled by Sandcastle, all I see in the Also See section is:
See Also
Expression
Select(String)
I would have expected to have seen:
See Also
for examples of filter expressions.
for a method that uses a filer expression.
Item 3: Maybe it should use a font style of Italic so that it stands out more.
Regards,
Michael.
Hi,
Re: Item 1
If I'm understanding Item 1 correctly, I believe it would be handled by David Smith's proposed fix in his Nov 29 posting on the "Documenting overloaded methods and Sandcastle" thread. Is this true? (Sorry, if there's a way to link to another posting, I don't know how to do it!) Anand has indicated that this fix will become standard in Sandcastle.
Regardless of the original design intent of <see> and <seealso>, I agree that it is very handy to be able to provide nondefault active text for the resulting link. In my case, I sometimes find that I need the qualified name of a member to be active, not just the member's simple name--that is, sometimes I want users to be able to read and click on ClassName.memberName instead of just memberName. As far as I can tell, the active text produced by the standard tag <see cref="ClassName.memberName"/> is simply memberName.
Re: Item 3
As I read the description of <c> in http://msdn2.microsoft.com/en-us/library/te6h7cxs.aspx , the tag's purpose is to distinguish code identifiers and keywords within a line of body text (as opposed to lines of code within a separate block). So, it would seem useful for <c> to use the same font as <code>, which appears to be courier (at least in the doc I've generated).
Since my company's style guide calls for courier, I would vote for <c> being defined to produce courier in the same size as the surrounding body text. But not everyone uses courier to distinguish code, so maybe there could be some way of specifying the desired font, e.g., through the SHFB?
In any event, I would not find it useful for <c> to produce italic, because I need italic to indicate code variables (like parameterName), not literals (like MyType).
Thanks,
Sue
All styles are controlled via the Presentation.css file in the Presentation\Prototype\Styles and Presentation\VS2005\Styles folders under the Sandcastle installation folder. If you don't like the default styles, you can modify those directly. If you are using the help file builder, you can make a copy, edit it to suit your needs, and add it as additional content to the project with a target folder of Styles\. This will cause it to overwrite the default stylesheet. The help file supplied with the help file builder does this to reduce the font size and adjust the spacing to my liking.
Eric
Hello Sue,
Regarding item3, I have no personal preference for what font/style should be used for the text in the <c> tags, it is just that as I was testing Sandcastle I found it difficult to distinguish this text and thought I would mention it. As Eric mentioned in his later reply, styles are controlled via the Presentation.css and can be changed to meet personal preferences so this is not really an issue, but item1 certainly needs to be addressed.
Michael.
Hello Eric,
Thank you for your advice on changing the presentation style. I will try this when I get a chance.
Michael
We will provide a fix for this in our December CTP.
Anand.
