Sandcastle May 2008 Release

May 30, 2008 at 6:54 AM
Wow! we finally have it. On behalf of the Sandcastle users, I say Thank you, Thank you, Thank you to Anand
and the members of the Sandcastle team who worked hard to make this release possible - God bless you all.

Please post comments, impressions and others on this new release.
I will be testing the <inheritdoc/> tag support extensively this weekend, never knew they will knock
this off - it seems MS is getting better!

Best regards,
Paul.
Editor
May 31, 2008 at 1:34 AM
The <inheritdoc/> implementation appears to lacks support for the cref and select attributes which I've got in my standalone version.  However, it does look like they made the supporting classes public so I can probably move my implementation into a build component.  I'll take a look into doing that and submit it as a feature request.

Eric
May 31, 2008 at 3:56 AM

>>Eric: lacks support for the cref and select attributes which I've got in my standalone version
I think they supported it like the JavaDoc (still testing, though), which seems to be the only
implementation in use. The cref was introduced by the NDoc 2, and the select was only raised
up in the thread

http://www.codeplex.com/Sandcastle/Thread/View.aspx?ThreadId=22873  

I will take a look at your documentations to see how you supported the select.
If the basic framework is there, options for what to retrieve would not be difficult to add.

I have just spend about half a day trying to fix a broken documentation, it turns out to be
a mistake on a page, which is only revealed by the new Sandcastle!

Best regards,
Paul.

Jan 13, 2010 at 6:42 AM

Hello,

This is a quick update. I have being testing the current release to see how the <inheritdoc/> is supported.

  • It turns out that the cref attribute of the <inheritdoc/> introduced by NDoc 2 is supported.
    That is, the following will work in a class not derived from System.Object...the sample class AClass derives from BClass:
    /// <overloads>
    /// Returns the text representation of this object.
    /// </overloads>
    /// <summary>
    /// Returns the text representation of this object, updated.
    /// </summary>
    /// <returns>
    /// <inheritdoc cref="Object.ToString"/>
    /// </returns>
    public override string ToString()
    {
        return base.ToString();
    }
    
    /// <summary>
    /// <inheritdoc cref="ToString()"/>
    /// </summary>
    /// <param name="testing">A new parameter.</param>
    /// <returns>
    /// <inheritdoc cref="BClass.ToString"/>
    /// </returns>
    public string ToString(string testing)
    {
        return base.ToString() + testing;
    } 
  • Adding to the inherited content is not supported.
    That is, the following will not work as expected, since the current implementation replaces the whole node...
    /// <summary>
    /// Gets or sets the text contents, updated.
    /// </summary>
    /// <value>
    /// <inheritdoc/>
    /// <para>
    /// Note that, this is the contents from the <see cref="AClass"/>.
    /// </para>
    /// </value> 
    
  • The select attribute discussed in the thread, <inheritdoc/>, is not supported.

Currently, I am trying to update the InheritDocumentationComponent to add the missing features.

If you have any request for the <inheritdoc/> tag, please let me know.

Best regards,
Paul. 

/// <summary>
/// Returns the text representation of this object, updated.
/// </summary>
/// <returns>
/// <inheritdoc cref="Object.ToString"/>
/// </returns>
public override string ToString()
{
    return base.ToString();
Jan 15, 2010 at 8:15 AM

Hello,

Yet another take on this. After reading the code for its implementations, I found that the select attribute of the
<inheritdoc/> is actually supported by Sandcastle.

The sample I used the other day for the selecting, <inheritdoc cref="Object.ToString()" select="remarks|example"/>
did not work because the base class in Object or system class, in which case the remarks and the example are not generated.
To be fair, the custom implementation by Eric does not work in this case too - tried it today.

On the Sandcastle select attribute implementation, it does not work for some cases when you supply some parts and try to
inherit others.

Case 1: This will not work, but works in Eric implementation (the first ToString() is the source)...

 

/// <overloads>
/// Returns the text representation of this object.
/// </overloads>
/// <summary>
/// Returns the text representation of this object, updated.
/// </summary>
/// <returns>
/// <inheritdoc cref="Object.ToString"/>
/// </returns>
/// <remarks>
/// This is just testing, AClass:ToString().
/// </remarks>
/// <example>
/// <code>
/// a = b + c
/// </code>
/// </example>
public override string ToString()
{
    return base.ToString();
}

/// <summary>A AClass to-string.</summary>
/// <param name="testing">A test parameter.</param>
/// <inheritdoc cref="ToString()" select="returns|remarks|example"/>
public string ToString(string testing)
{
    return base.ToString() + testing;
}

Case 2: But this modified version of the ToString(string) will work...

 

/// <inheritdoc cref="ToString()" select="summary|returns|remarks|example"/>
/// <param name="testing">A test parameter.</param>
public string ToString(string testing)
{
    return base.ToString() + testing;
}

Case 3: Also, this will work...

 

/// <inheritdoc cref="ToString()" select="summary|param|returns|remarks|example"/>
public string ToString(string testing)
{
    return base.ToString() + testing;
}

Case 4: And this works...

 

/// <inheritdoc cref="ToString()" select="summary|param|returns"/>
public string ToString(string testing)
{
    return base.ToString() + testing;
}

By including discussion feature (the select attribute), the Anand and his team did a great work with the <inheritdoc/> tag,
which is largely complete and should satisfy most needs.

I will now try many examples and fully document what works for reference. Have a nice weekend, and God bless you.

Best regards,
Paul.