Support for <summary cref="..."/>

Oct 2, 2009 at 1:54 PM

Hi,

I am currently in the process of completing the inline code documentation of our application to hand it over to our client. So far, Sandcastle does a good job at it. There's just one thing I didn't manage to get to work: Summaries linking to another member's summary. Here's an example:

/// <summary>
/// A's summary
/// </summary>
public void A()
{
}

/// <summary cref="A"/>
public void B()
{
    // Does the same as A(), so give it the same documentation
}
The VS2008 compiler doesn't mark this as a warning, so it can resolve the link target. (It would rise a warning if I changed the link target to something invalid.) This syntax is also used in the MSDN library where it talks about the <see> tag.

I would expect that B() has the same summary as A() in the generated documentation, but instead B() has no summary at all.

This is all that is left in the resulting HTML file: <div class="summary"> \n </div> (where \n is a line break and a few spaces in the file)

Since the <summary cref="..."/> is contained as-is in the comments.xml file, I assume it would be Sandcastle's job to resolve those links.

Any idea about what I can do to make it work, or is it a bug?

Oct 2, 2009 at 3:17 PM

>>The VS2008 compiler doesn't mark this as a warning, so it can resolve the link target.
I think it is worth reading the documentation of stuff you use since that is the easy way to minimize
coding bugs in your program. 

>>This syntax is also used in the MSDN library where it talks about the <see> tag.
Please read the documentation well, there is nothing like that.

>>Since the <summary cref="..."/> is contained as-is in the comments.xml file
Is this what the specification says...

>>I assume it would be Sandcastle's job to resolve those links.
No, it is your job to document your codes well. So, learn how to do it.

>>Any idea about what I can do to make it work, or is it a bug?
The closest you can get is extended tag named <inheritdoc/>.

If you use a lot of such documentations, then use external documentations and the <include/> tag.

Best regards,
Paul.

Oct 2, 2009 at 4:38 PM
SelormeyPaul wrote:

>>The VS2008 compiler doesn't mark this as a warning, so it can resolve the link target.
> I think it is worth reading the documentation of stuff you use since that is the easy way to minimize
> coding bugs in your program. 

What stuff?

>>This syntax is also used in the MSDN library where it talks about the <see> tag.
> Please read the documentation well, there is nothing like that.

Please open your MSDN library and enter this URL:

ms-help://MS.VSCC.v90/MS.MSDNQTR.v90.de/dv_csref/html/0200de01-7e2f-45c4-9094-829d61236383.htm

If that doesn't work for you, go to the index, select "<see> (C# XML tag)" and scroll down to the example. That is exactly the place I mean. Don't tell me it's not there.

>>Any idea about what I can do to make it work, or is it a bug?

>The closest you can get is extended tag named <inheritdoc/>.

That indeed looks good.I've tried it out, but it only works half way: The summary and remarks sections are added to the member page, but the summary on the All Members list page is empty for that property. So it's also not quite what I was looking for.

BTW, as I was further investigating things, I did find something that looks like a Sandcastle reference, at ewoodruff.us. Why isn't that linked from the Sandcastle homepage at CodePlex? The only thing I can see here is missing Wiki pages. From what I get to see here on the project homepage, I get the impression that Sandcastle is very poorly documented. I came this far today only by trying out things on my own, not by reading any kind of hidden documentation.

And here's another web link that seems to relate to this topic: http://social.msdn.microsoft.com/forums/en-US/devdocs/thread/2aae0bfb-4d4a-4b1b-912e-c9121385a4c9 But it's also unresolved.

Maybe I'll just forget about such content copying for now and copy those two lines in the source code in the first place until there's a real documentation on stuff.

Editor
Oct 2, 2009 at 7:30 PM

Sandcastle provides basic support for the <inheritDoc /> tag.  I wrote a standalone tool that provides more support for it including support for the cref attribute and filtering.  It will solve the problem of the documentation not showing up on the member list pages too.  If you are using the Sandcastle Help File Builder, support for it is built in.  If using Sandcastle by itself or with another community tool, you can download it as part of the Standalone Build Components.  Both can be downloaded here.  More info on the extended support for the inheritDoc tag can be found here.

I believe that at one time, the online MSDN documentation for either <summary> or the example for <see> was incorrect and did show a cref on a summary element in the example but that has since been corrected.  The Sandcastle Help File Builder you found reference to at ewoodruff.us (my site) is linked to from the home page of the Sandcastle project.  You'll find it in the Related Projects box along with other related projects near the bottom right of the home page.  These are tools developed by community members to make using Sandcastle much easier and aren't produced by Microsoft.

Eric

Oct 2, 2009 at 8:24 PM

Eric,

thank you for your reply.

I don't exactly know what tool I am using. I just found Sandcastle, downloaded it, read the requirements and installation documentation and ran the installer. There was no start menu entry after it and no more documentation pages written, so I started to look around on my hard disk and figure out on my own what I could do. I found that example directory and took the batch file in it to generate a CHM file for our application. It worked quite well, I could apply the "remember code language selection" patch from another thread here, translate things to German like in the MSDN library. It's just a bit slow, 13 minutes for ~1 MB .exe assembly.

But after all I still don't really know much about the Sandcastle project or its structure. From the developers list, I assume it's managed or developed by Microsoft, although it's not the usual Microsoft product release quality. There's nothing more to learn from the homepage. Nothing about community projects, nothing about derived versions that may add features or fix bugs, nothing about how to use it to do things right. Maybe it's about time for somebody who knows it to write a documentation...

A colleague I talked to today was surprised that I managed to get Sandcastle to working. Others have given up on it, too, before. They either dropped that task or used NDoc again. That's faster, has a GUI and seems to have more features. From what I've seen, it has other bugs, comes with an older MSDN page design and may be less flexible. Either way, .NET source code documentation generation doesn't seem to be a mature matter, even in 3.5 days.

Editor
Oct 3, 2009 at 2:40 AM

You're using just the Sandcastle tools by themselves.  They can be hard to use due to lack of documentation.  Most of the info on usage is spread throughout the various posts on the Sandcastle blog.  That's why it is better to use one of the community tools such as the Sandcastle Help File Builder or DocProject.  SHFB is a standalone GUI that provides a set of features similar to NDoc.  DocProject is a Visual Studio add-in.  Using either of those lets you use Sandcastle without having to know how to make it work.  If you can set some project properties and push the Build button, you can get a fairly decent looking help file.  Both also provide many features over and above the stock Sandcastle tools.  I'd encourage you to look at them before giving up on Sandcastle altogether.

SHFB contains a help file with all the necessary details about its project settings, the additional build components, plug-ins, and walkthroughs on getting started.  As for bug fixes, download and apply the Sandcastle Styles patch.  You'll find that it takes care of the common problems and adds some new features that make the help files look better.  You'll also find some other tools and a MAML guide (Microsoft Assistance Markup Language) that will help you get familiar with it if you need to write conceptual content for your help file (additional topics such as introductions, How-Tos, Walkthroughs, etc.).

Sandcastle is slower than NDoc mainly due to its architecture.  BuildAssembler, which actually renders the topics, is the slowest step.  It's written to be extensible and is composed of many different build components.  You can add new build components to add new functionality.  With that flexibility comes a performance penalty but overall it is worth it.  The ResolveReferenceLinks2 component can slow things down considerably because it contacts the MSDN web service to resolve links to the online base framework member topics.  This can be mitigated to a certain extent by using the cached build components available in the standalone build components I mentioned.  If building a Help 2 file you can configure it to render index links to the API topics instead so that it links to the local MSDN topics when your help file is merged into the main help collection which bypasses the need to look them up via the web service at build time.

Eric

 

Oct 3, 2009 at 7:03 AM

>>lonelypixel: Don't tell me it's not there.
I see. Yes, it is there, and that is why I say read well. If you are just copying what you see and
making no effort to understand it, then you need to be cautioned.

I read your post and could not determine where you are; newbie, hobbyist or professional.
I checked your profile, and even though that was your first post you have registered at CodePlex since
February and in the very first statement you are about to release a product!

So, I decided to treat you as a professional and question your approach.
Sorry, that was what I thought was good for you. Off course, I know you will not like it.

Documentation is part of the planning process when designing a software product, so I found it
difficult to understand that you are now going through this process when you are about to release the
product.

Please take the time and get this process well, otherwise you will face more problems with your clients,
and if they are as noisy as Japanese clients then you could easily loose your income.

There is enough information on Sandcastle. It is a bit slow because of what it does. The new MSDN format is
more complex - one of the main reasons why NDoc does not cut it, ... using the GUI tools
is going to make it even slower, since they add more layers/processing to the base (in some cases more
memory requirements) - for now, you will have to accept this.

If you need more information on the XML comments and how the various tools NDoc, Sandcastle extended it,
please read the documentations here

http://www.dynicity.com/products/XmlDocComments.aspx

Best regards,
Paul. 

Oct 6, 2009 at 8:12 AM

The <inheritdoc/> tag does it well (at least using SHFB), thank you.

The PDF reference you pointed to doesn't include the <inheritdoc/> tag at all, it looks like it could need an update...