How to add topic for attached dependency property?

Topics: Developer Forum, User Forum
Jan 23, 2012 at 5:35 PM

I have to use a lot of attached dependency properties in my project. But manually create the xml-file documentation and publish it as a documentation source in the SHFB is very difficult. Is there another way? For example, adding a special topic...

Jan 23, 2012 at 7:48 PM

Are you referring to the auto-generated topics under the Attached Events and Attached Properties categories in the TOC where the syntax section say "See GetXXX, SetXXX"?  I think these may be another cases where I need to extend the Show Missing component to auto-document the member and perhaps have it refer back to the related public field or perhaps have the inherited documentation tool pull in the documentation from the public field for use on the auto-generated property.

I'm rather new to WPF so up until a few months ago I didn't know what I was looking at with regard to the XAML related features of Sandcastle.  Now that I do, I plan on adding proper support for them.  There's also a build component that apparently adds XAML syntax sections to the appropriate topics so I'll be adding support for that too.  I'll see what I can do for the next release of SHFB.



Jan 25, 2012 at 2:32 AM

To follow up on this, I've update the GenerateInheritedDocs tool to auto-document the generated attached property and attached event elements with the comments from the field so that they at least get default comments rather than a "missing comments" message if they are not documented using a standalone XML comments file.  Since they are auto-generated, there really isn't anywhere to attach documentation to them in the code other than on the backing field.  If you want the comments on the auto-generated property/event to differ from those on the field, you really do need to manage them with a standalone XML comments file.



Jan 25, 2012 at 5:18 PM

You mean this method? I know about it, but I would like to use a more convenient method, if one exists.

Jan 25, 2012 at 7:56 PM

Right now, that's the only method that can be used if you want comments separate from the field.  After giving it some thought, here's one possible solution that lets you keep the comments with the field.

The compiler doesn't care about non-standard XML comments element so you could do something like the following.  Declare the comments for the field in the normal fashion and then declare the comments for the auto-generated property/event in an <AttachedPropertyComments> or <AttachedEventComments> element like this:

/// <summary>
/// This declares the <see cref="P:MyNamespace.MyClass.SomeValue" /> attached property.
/// </summary>
/// <AttachedPropertyComments>
/// <summary>
/// These comments are for the attached property itself.
/// </summary>
/// <value>Info about the value</value>
/// <remarks>Some remarks about the property</remarks>
/// <example>
/// <para>A code example</para>
/// <code>Code goes here</code>
/// </example>
/// </AttachedPropertyComments>
public static readonly DependencyProperty SomeValueProperty =
        typeof(string), typeof(MyClass));

The GenerateInheritedDocs tool would then remove the AttachedPropertyComments/AttachedEventComments content from the field comments and add them as the comments for the related auto-generated member.  Would that be acceptable?  I'm open to suggestions.  Something like that wouldn't take long to implement so I could get it into the next release which I'm hoping to get out within the next week or so.



Jan 31, 2012 at 12:14 PM
Edited Jan 31, 2012 at 12:17 PM

Yes, this is the best solution! Thank you very much!

I tried to do something like that (changing the code in main_sancastle.xsl), but I'm not very good at XSL and I was able to add only new section in property/field documentation.

Jan 31, 2012 at 3:07 PM

I thought that it would be fine so it's built into the latest beta release.