Issues with static classes and members

Topics: General Questions, Help 1.x/2.x, Sandcastle
Jul 26, 2010 at 9:38 AM

I am not yet clear on where SandCastle stops and DocProject begins. Please feel free to refer me to the SC project for resolution of these issues. If nothing else at least the issues will be documented here.

I have a project containing a collection of extension methods. All classes are static, and all methods in these classes are static. I'm generating a CHM via Help 1.x and filtering out Inherited members.

When filtering out Inherited members, I'm not even getting the "public static" methods. I've tried recreating the project from scratch several times to see exactly what triggers this. Depending on the template used, the resulting CHM contains: 1) the public static classes, with one doc page for each class, just none of the methods for any of the classes; or 2) just the top-level namespace node and absolutely nothing else under it.

I'm still experimenting in this area. Should I come up with specific settings and specific issues, or should we consider "static methods" an area that is subject to being problematic?

Since we're here, I'm understanding the differences between the various Sandcastle style templates - hana, VS2005, etc. Each one does something a little different and none of them do what "I" want. I suppose this is a good opportunity to get to learn exactly how these work  - as if I have time. ;)

Thanks.

Coordinator
Jul 27, 2010 at 3:03 PM
Edited Jul 27, 2010 at 3:05 PM

Hi,

The vs2005 style is really the only style that is fully functional and supported by Sandcastle, AFAIK.

When you create a new DocProject or DocSite it imports all of the chosen presentation style's content into the new project.  Feel free to experiment on the files within your project's Help\Presentation\ folder to customize Sandcastle to meet your needs.

I assume that you're using the Inheritance Filter?  That's a custom dynamic filter that I wrote for DocProject.  It relies on Sandcastle's MRefBuilder tool to produce a reflection XML file that it uses to figure out the inheritance relationships, however, so it might not work the same for all presentation styles.  It should work fine for static members though, but I'm not sure about extension methods in particular - they're a somewhat different animal I think, at least as far as Sandcastle is concerned.

Just a guess, but perhaps you need to enable the following add-in for Sandcastle's MRefBuilder tool to support extension methods?  (Unless I'm misunderstanding the issue, of course.)

    <addin type="Microsoft.Ddue.Tools.ExtensionMethodAddIn" assembly="%dxroot%\ProductionTools\MRefBuilder.exe" use-gac="false" />

I found that suggestion here: http://sandcastle.codeplex.com/Thread/View.aspx?ThreadId=52675

- Dave

Jul 27, 2010 at 7:01 PM

Thanks for the guidance, Dave. Yes, I'm using your Inheritance Filter, and it seems to work fine for VS2005 styling. I just get my class members, none of the base members.

For extension methods, I added the 'addin' line to MRefBuilder.config, under dduetools\addins. It did not make a difference - the CHM for a VS2005 style does not show methods as being extension methods. From the discussion you linked, I'm understanding that the style templates may not yet include the hooks to support the addin. I will spend some more time on this later. I may need to selectively patch files from the latest SandCastle release even though we're using an older release for DocProject.

If VS2005 is the only style we can/should use, please add that to the DocProject installation notes. I'm coming at this from a DocProject perspective because I want to create docs from VS. I'm not coming at it from a SandCastle view and I don't know what's supported there. I sort of started from that view, installed the latest release and patches, and then found out here that I need to go back to an older release. As you can see, it's tough for someone just getting familiar with this sub-world of document generation to know how to piece it all together. I checked out NDoc several months ago and concluded it was dead - this is really the first time I've looked closely at dressing up code docs, and originally just separating the concepts of SandCastle and DocProject was a challenge for me.

I have a lot of questions about the generated documentation but I'm concerned that if I take questions to SandCastle (Eric?) that I'm going to be told the answers are all resolved in the latest release. For example:

  • Where do I change the email address for Send Feedback?
  • How do I properly remove the Namespace and Assembly sections in pages? (Removing the topics from the XML doesn't seem to be the right way to do it.)
  • Can I eliminate the generation of Syntax examples for specific languages? (Without the ability for CHM files to maintain state for preferences, I don't want to have to deal with viewing the multi-language syntax every time I generate a new doc.)
  • Can I eliminate the See Also back to the primary namespace? It's the only namespace in the current project so no link is required.

Are those questions for SandCastle or DocProject?

Thanks again.

 

Coordinator
Jul 29, 2010 at 12:15 AM

Hi,

Thanks for the feedback, it's useful.  To answer your specific questions:

> Where do I change the email address for Send Feedback?

Sandcastle uses XML files called "content" files to provide localizable text, HTML snippets and data to the presentations.  Each presentation style has its own content files.

You'll find these files within your project's Help\Presentation\Style\Content\ folder.  You can also use the Topic Designer to edit them.  Note, however, that some values are not persisted correctly by the Topic Designer due to non-visual XML values inside the content files; e.g., editing the vs2005 footer should only be done manually in the XML file or on the source tab in the Topic Designer window, but not in the design tab.

If I remember correctly, the send feedback email address is located in the feedback_content file and the content item is fb_alias.

> How do I properly remove the Namespace and Assembly sections in pages?  (Removing the topics from the XML doesn't seem to be the right way to do it.)

You'll probably have to modify the Sandcastle XSLT transformation to do that.  Look in your project's Help\Presentation\Style\Transforms\ folder.  The main_sandcastle.xsl file is the main one for reference builds (not main_reference.xsl), so I'd check in there first.

> Can I eliminate the generation of Syntax examples for specific languages?

Yep.  You can edit the list of syntax generators in the DocProject Properties window for your project.  In the properties window, there are four properties that correspond to the different Sandcastle build component stacks.  Each one is required for a different type of build.  You'll need to expand the Help 1.x reference build component stack.  You'll find some more information about this feature here:

http://docproject.codeplex.com/wikipage?title=How%20To%20Use%20Third-Party%20Build%20Components%20in%20DocProject

The syntax generation component should be located within the first IfThenComponent in the stack, under its Then branch.  I believe that you can edit the list of generators in the component's editor.

Note that you don't have to use this feature of DocProject, if you feel more comfortable editing the Sandcastle config file directly.  The config file is located in your project's Help\Presentation\Style\Configuration\ folder.  You'll want to open the sandcastle.help1x.config file and search for "SyntaxComponent".  You'll see the list of syntax generators as nested XML elements.

> Can I eliminate the See Also back to the primary namespace? It's the only namespace in the current project so no link is required.

Again, this will probably require a modification to the Sandcastle XSLT files.

- Dave

Coordinator
Jul 29, 2010 at 12:23 AM
Edited Jul 29, 2010 at 12:24 AM

Hi,

I just want to add that I doubt any of your particular questions have been "resolved in the latest release".  Sandcastle is customizable because you can modify its XSLT, config and content item files as you wish.  DocProject simply integrates this feature into a Visual Studio project template, provides several UI dialogs and tool windows to make managing the most common settings easier, and finally automates the Sandcastle build process for you.

Unfortunately, Sandcastle doesn't have the concept of a global settings file containing abstract items that apply to every presentation style.  That might be nice though, so maybe somebody will add it eventually :)

- Dave

Jul 29, 2010 at 4:59 AM

Dave - that's a real gold-mine of information there.  It's a roadmap for solving categories of problems. Metaphorically speaking, I always prefer giving and receiving a fishing pole that will last for a lifetime rather than a fish that will last for a day. I thank you sincerely for the same and will make good use of the info.