Sandcastle Styles Patch Rev 3 Now Available

Editor
Jan 4, 2010 at 5:43 AM

Revision 3 of the Sandcastle Styles patch is now available from http://www.codeplex.com/SandcastleStyles/Release/ProjectReleases.aspx.  It contains various patches and feature enhancements for the Sandcastle May 2008 Release (Version 2.4.10520). See FixList.txt in the ZIP file for a list of the patches applied and links to the related Sandcastle project work items.

This change set includes all updates from the Sandcastle July 2009 source code release with the Sandcastle Styles patches applied to it. In addition it in includes the following updates and fixes:

  • Fixed a bug in the July 2009 source code release that caused missing enum member descriptions in the VS2005 style.
  • Added a value column to enum member tables to show the numeric member value.
  • Added some missing resource items to the Hana and Prototype styles.
  • Added support for the "definition" list type on "list" XML comment elements.
  • Added support for XML comment term element in bullet and number list styles
  • Added support for the "start" attribute on "list" XML comment and MAML elements that use the number/ordered style to allow the definition of the starting number for the list instance.
  • Added an MRefBuilder.exe.config file to allow MRefBuilder to parse .NET 4.0 assemblies (current as of the VS 2010 Beta 2 release).
  • Add changes to support code contract elements in the VS2005 style. Updated FixList.txt to remove the four fixed items and add references for the new bug fixes and changes.


This file set can be used to overwrite the corresponding Sandcastle May 2008 release files with or without a prior Sandcastle Styles patches applied to them and can be used in conjunction with the May 2008 Sandcastle executables. The only thing you cannot do is produce F# syntax sections since the May 2008 release does not contain the needed syntax declaration component. If you need to produce F# syntax sections a copy of the syntax generator component that does work with the May 2008 Sandcastle release can be found in the Standalone Build Components (v1.8.0.3 or later) download available from the Sandcastle Help File Builder project.

Editor
Jan 5, 2010 at 2:58 AM

I just issued a refresh of the Rev 3 patch that includes an additional fix that was missed.  The VS2005 main_sandcastle.xsl transform was missing a variable declaration needed by the version builder elements.  If you downloaded the version released on 01/03/2010, just redownload the latest update and reapply it to obtain the extra fix.

Eric

 

Jan 18, 2011 at 1:46 PM

Hello, Eric -

I'm having problems documenting some generics using Sandcastle June 2010 release, so I'm trying to roll back to the May 2008 release. Could you recreate the old styles patch release?

Thanks,
       -Steve

Jan 18, 2011 at 2:04 PM

Hello Steve,

It is now public, please report on any difference in the generic problem.

Best regards,
Paul. 

Jan 19, 2011 at 4:49 PM

Hello Paul -

Well, there is a difference, but it's not what I was hoping for.

With the simple example:

/// <summary>A generic interface.</summary>
public interface ITest<T>
{
  /// <summary>A method.</summary>
  /// <param name="param">A parameter that is of a generic type.</param>
  void Test(Func<int> param);
}

The output from the old MRefBuilder skips over the Test method completely, leaving just an empty interface (!). The output from the new MRefBuilder spits out "M:ClassLibrary1.ITest`1.Test(System.Func`1)", which I believe is incorrect.

VS outputs this doc id in the xml doc file: "M:ClassLibrary1.ITest`1.Test(System.Func{System.Int32})", which I believe is correct.

[note: the strings above were written from memory, but I'm almost sure they're right].

I'm actually suspecting a bug in the CCI library used by MRefBuilder; the doc id output seems to be using the (open) generic type instead of the constructed type for method parameters in generic interfaces. After I get a decent repro going, I'll submit it as a bug (to CCI or Sandcastle, as appropriate).

       -Steve

Editor
Jan 19, 2011 at 7:15 PM

Be aware that the May 2008 release doesn't parse .NET 4.0 assemblies correctly.  In classes with methods containing generics, it does tend to incorrectly remove all member from the class.  That was fixed in the June 2010 release but a side-effect is that you see the new bug where it doesn't always generate the correct member IDs for those with generic parameters and you end up with a mismatch between the IDs in the reflection info file and the XML comments.

Eric

 

Jan 19, 2011 at 8:29 PM

Eric -

Is this already a known issue for the June 2010 release? I've looked over MRefBuilder's source and I believe the fault lies with CCI, but it's not possible to say for sure. I tried to use CCI a couple years ago but gave up due to lack of documentation (and API churn).

I'm thinking I'll just file an issue for the Sandcastle project, and they can distill it into a CCI issue if they want to. Unless this is already a known issue.

       -Steve

Editor
Jan 19, 2011 at 10:20 PM
Edited Jan 19, 2011 at 10:20 PM

I don't think it has been reported, not here anyway.  I'd go ahead and create a workitem with any examples you have.  If it's a duplicate, they can close it out later.

Eric