A few Sandcastle bugs...
Hello again, long time - no post.
I've recently updated to using the March CTP (VS2005 style only). Many thanks, it's excellent. Hardly any missing features (I mean features which I need, others may disagree!). Also, very few bugs which I have noticed.
However, here is a list of things I have found. I'm sure that these have been reported elsewhere but I haven't checked all posts since the March CTP came out.
1 - I have seen the following warnings from BuildAssembler:
1.a - Warn: SharedContentComponent: Missing shared content item 'fieldsindexentry'.
1.b - Warn: SharedContentComponent: Missing shared content item 'group'.Warning 1.a appears for all enumerations and also any classes/structs with public or protected fields.
Warning 1.b is rather odd. It appears only when building an AllMembers page. Furthermore, I have only seen it occur for classes which inherit from a generic class (some which specify the generic parameter and some of which leave it generic). For each occurrence of this warning, one of the member descriptions (always a non-overridden inherited member with no overloads) will have the main description text twice (on two separate lines which exactly match), followed by the automatically generated third line (Inherited from MyClass<T>.). I have not been able to discern the pattern any better than this!
2 - Member name column heading for enumeration members table is incorrect. It reads Class and should read Member name.
3 - Description in member list tables is incorrect for members which override a base class member. The base class name is missing. E.g. when overriding the Equals method the description ends with the automatically generated text (Overrides .Equals(Object).) and this should read (Overrides Object.Equals(Object).).
4 - Description in member list tables for overloaded members misses the summary. It simply reads Overloaded.. This should be followed by the <overloads> summary text.
5 - All the various member list pages for generic classes include a Type Parameters description at the top (naming the parameter but missing its summary). This should be removed from those pages.
6 - Member list tables for inherited methods which are overloaded in the base class are incorrect. Each inherited overload is reported separately with a link to the particular overload; whereas only one entry should be reported as Overloaded. followed by the <overloads> summary, with a link to the common overload page if possible. [That may be tricky for .NET framework links.]
7 - Common page for overloaded methods has incorrect header:
7.a - For non-generic classes the header reads .MyClass.DoMyThing Method. the initial dot should not be present.
7.b - For generic classes you get the heading .MyGenericClass<T, T>.DoMyThing Method. It should read MyGenericClass<T>.DoMyThing Method.8 - For an overloaded generic method (whether in a generic or non-generic class) then the method's type parameter is listed on the common overload page but the description is missing. I think the type parameter should be removed from the page.
I hope this is of some help.
David Smith
All Replies
Hi David,
Bucket wrote: 1 - I have seen the following warnings from BuildAssembler:
1.a - Warn: SharedContentComponent: Missing shared content item 'fieldsindexentry'.
A typo in the reference_content.xml file causes this.
Hxcomp.exe: Warnings, Help Collection Integration and StdOut
Excellent. Thanks Dave and David. I am really behind on these forum posts and I promise to get to them this week and resolve some of the user issues.
Anand..
Anand,
A few more bugs, not included in the original list (i.e. in the first post of this thread)... [Numbers continue from where I left off.]
9 - Constructors title and index entry has preceding dot which should be removed. Also, for generic classes, the type parameters are not correct. E.g. .MyGenericClass<T, T> Constructor should be MyGenericClass<T> Constructor. [This looks like the same bug as 7, 7.a and 7.b.]
10 - Table in Overloads common page is incorrectly generated. The <br /> at the end of each description appears after the </td> and it should be before the </td>. This is a bug in utilities_reference.xsl, lines 288 and 506. (VS2005 March CTP).
11 - Property value header incorrectly reads Field Value and this should read Property Value.
12 - Operators and conversions do not appear in the member list tables unless they are overloaded (e.g. I define two multiply operators).
13 - If operators or conversions are overloaded within a particular class, they appear in the member list tables as overloaded but the name is incorrect on the common Overloads page heading (e.g.) Multiply Method and this should be Multiply Operator to be consistent. (or op_Multiply Method as in .NET, see 16 below).
The rest of the items are not bugs... they simply highlight differences between the Sandcastle generated docs and the actual .NET docs. These are all matters of preference. However, my preference in most cases is to duplicate the .NET style.
14 - When using <typeparamref name="T"/> the generated T in the documentation is not in italic. In .NET docs, type parameter references are in italics.
15 - Method parameter descriptions in .NET simply have the parameter name and, on the next line, its description. Sandcastle inserts an extra line between the two giving the parameter type.
16 - Operators are named differently in .NET: [I prefer Sandcastle in these cases!]
16.a - .NET uses (e.g.) op_Addition Method and Sandcastle uses Addition Operator.
16.b - .NET uses op_Explicit Method and op_Implicit Method and Sandcastle uses Explicit Operator and Implicit Operator.
That's all for now!
David
P.S. The doc for the System.Decimal structure contains many examples of operators and conversions.
David,
I am checking our internal builds and it appears items 1, 2, 7, 9, 10 are fixed. I will need to verify this. Items 15 and 16 are by design.
Let me verify the rest and provide an answer.
Anand..
