Identifying API changes with Sandcastle?

Jan 20, 2009 at 8:01 PM
Hello,
  We had been using NDoc, but have moved over to Sandcastle for almost everything.  The last function is not documentation exactly, but we use the documentation to accomplish it.  We are maintaining and enhancing an API that our customers use to talk to our hardware.  We need to pay close attention to changes we make to the API.  We had been using a custom application on top of NDoc to create a report of the changes.  It seems to me that it should be possible to compare the "old" XML documentation file and the "new" one to get the differences.  Obviously I could write a program to do this, but it seems like I should be able to do something similar with an XSL template.  I am not very familiar with XSL, but if someone could point me in the right direction I would really appreciate it.  Alternately does Sandcastle offer any type of diff tool to show the differences between doc file A and doc file B?

Pat O
Jan 20, 2009 at 10:41 PM
>>Pat O: Alternately does Sandcastle offer any type of diff tool to show the differences between doc file A and doc file B?
Not directly, but the version information support may do, take a look

Part 1: http://blogs.msdn.com/sandcastle/archive/2007/10/03/sandcastle-september-2007-release-versionbuilder.aspx
Part 2: http://blogs.msdn.com/sandcastle/archive/2007/10/24/part-2-version-builder.aspx

Best regards,
Paul.
Jan 21, 2009 at 12:44 AM
Hi Pat,

If you want to track changes to the API then I suggest using a diff tool (like Windiff or the various tools provided with source control systems) to compare code files directly.  I'm not sure what value there is in comparing changes to XML documentation comments, but if you need it then just use a diff tool to compare the XML documentation file output from the code compiler itself.

Alternatively, although I don't see this as adding any extra value, you could use a diff tool to compare the XML reflection files that Sandcastle's MRefBuilder.exe tool generates from two different versions of the same assembly.  (I think this is what Paul was recommending by pointing you to the version builder tool, but I don't think it will meet your needs if you're looking for a straight comparison of the changes between two versions of the same assembly.)

- Dave
Jan 21, 2009 at 1:15 PM
Thanks for the links Paul, I think that may give me the information I need.  At least some of it. 

Dave, I think you misunderstand what I mean by changes in the API.  I know there will be implementation changes in different versions of the SDK.  The information I am seeking is what changd in the parameters and methods available to the user of the SDK.  Obviously I will have a list of changes I expect happened, but I want a process in place to tell me all the changes that happened so I can check my work.  Running a diff on the code is essentially useless, because so much code changed and so little of it has to do with that public interface (API) to the SDK.  Sandcastle helps me in that I have already filtered the XML files to only include the documentaiton for the methods I expect people to use (in other words the API).  Still, doing a diff on the output XML from two different versions is not sufficient.  First I have noticed that they are not necessarily in the same order.  Even in the same order, addition of a single class is enought to cause the rest of the files to appear different.  So you see I need a tool that will attempt to line up the XML elements, then report what is new, what is missing and what has changed.  From there I plan to write a report and possibly release notes for each release of the SDK.

Pat O
Jan 21, 2009 at 1:54 PM
Hi Pat,

There is no such tool.  I guess you can write an XSLT file that will take the version builder output (a single XML reflection file that contains additional version information for each API) to generate an XML file that contains what's new and what's missing, but you'll still have to write your own diff tool to discover what has changed; e.g., parameter names, return types, etc.

- Dave
Jan 21, 2009 at 2:45 PM
What does it take to write a component for Sandcastle?  Is there a doc someplace?  Can I get a look at the source for the VersionBuilder component?

Pat O
Jan 22, 2009 at 12:07 AM
>>Pat O: What does it take to write a component for Sandcastle?
XPath :) that is all, it is that simple.

>>Pat O: Is there a doc someplace?
There is no official documentations - this is part of my effort with the Sandcastle Assist.
However, there is a good article by Eric on the custom component here...
http://www.codeproject.com/KB/cs/SandcastleComponents.aspx

>>Pat O: Can I get a look at the source for the VersionBuilder component?
The source of some of the utility tools are not released, and I am not sure this one
is available - possibly it was created by another group at Microsoft, not the main Sandcastle team.
Please, post a thread and request that or directly write to Anand, since he is currently updating the
source code tree here at Codeplex, this may be considered.

Best regards,
Paul.
Jan 22, 2009 at 7:36 AM
Hi Pat,

I see no advantage to performing a diff operation in a build component.  Build components are executed once for each topic and are supplied with an XML document that contains far more information than you'll need for a simple diff.

I suggest running an out-of-band diff instead (like the Version Builder tool).  Sandcastle's build process is highly flexibly - you can inject your tasks before or after Build Assembler is executed.  If you're using a batch or MSBuild script, then it's quite easy to add additional tasks into the process.  If you're using a tool that automates Sandcastle, such as DocProject or Sandcastle Help File Builder, read their documentation for instructions on how to add new tasks into the build process.

- Dave