Sandcastle: Comment references

Sandcastle: Comment references

• Ricardo 8a

  Marcel,

  This can be achieved by making some changes to sandcastle.config and main_sandcastle.xsl files. It should be something like the following:

  In Sandcastle.config: the following needs to be added.

  <component type="Microsoft.Ddue.Tools.CopyFromIndexComponent" assembly="..\..\ProductionTools\BuildComponents\BuildComponents.dll"> <copy name="comments" key="string(/document/reference/implements/type/@api)" source="summary" target="/document/reference/implements" /></component>

  In Main_sandcastle.xsl: The following needs to be added.

  <xsl:apply-templates select="/document/reference/implements/summary"/>

  Let me know if this helps. Would you like to see Sandcastle support this

  Anand..

  
  
  

• Peter R Hawkes

  Hey Anand,
  
  thank you as a start for the quick reply. Unfortunately, Sandcastle doesn't find the key:
  
  Info: CopyFromIndexComponent: Instantiating component.
  Error: BuildAssembler: An error occured while initializing the build component 'Microsoft.Ddue.Tools.CopyFromIndexComponent' in the component assembly 'C:\Program Files\Sandcastle\ProductionTools\BuildComponents.dll'. The error message and stack trace follows: System.Collections.Generic.KeyNotFoundException: The given key was not present in the dictionary.
  at System.ThrowHelper.ThrowKeyNotFoundException()
  at System.Collections.Generic.Dictionary`2.get_Item(TKey key)
  at Microsoft.Ddue.Tools.CopyFromIndexComponent..ctor(BuildAssembler assembler, XPathNavigator configuration)
  
  I used the Sandcastle Help File Builder and edited its sandcastle.config. Futhermore I customized the main_sandcastle.xsl. But I don't know if it got invoked by the SHFB.
  
  Shall I run Sandcastle without the Help File Builder This could be more difficult than I can cope with. Are there any docs
  
  And finally: Yes. I would be really grateful if I could choice between making a new comment ("override comment") or copying the existing one from the derived class in a future version of Sandcastle.
  
  I'm looking forward to hear from you again,
  Marcel
  
  
  

• CodeDjinn

  Yeah, you're right!
  
  It wasn't in the right place like that. I put it on the top.
  
  Now, the Sandcastle Help File Builder works fine, but it still doesn't produce the results. Maybe there's another notation I should use with the code. Or I really should switch to the command line use of Sandcastle.
  
  One more code example:
  
  namespace CMF.enviroment.converter
  {
  /// <summary>
  /// A simple iterator which provides access to the
  /// collected <see cref="Module" />s.
  /// </summary>
  /// <typeparam name="T">Type of <see cref="Module" /> this
  /// <see cref="IModuleIterator{T}"/> provides</typeparam>
  public interface IModuleIterator<T> where T : Module
  {
  /// <summary>
  /// Indicates if there are at least one more
  /// <see cref="Module" /> left.
  /// </summary>
  /// <returns><para>true - the iterator can offer one
  /// more <see cref="Module" /> </para>
  /// <para>false - otherwise</para></returns>
  bool hasNext();
  
  /// <summary>
  /// Returns the current instance of
  /// <see cref="Module" /> the internal pointer shows.
  /// </summary>
  /// <seealso cref="IModuleIterator{T}.hasNext"/>
  /// <returns><para>An instance of <see cref="Module" />
  /// if one is left</para>
  /// <para>null - otherwise</para></returns>
  T next();
  }
  
  /// <summary cref="IModuleIterator{T}" />
  /// <seealso cref="IModuleIterator{T}" />
  public class ModuleIterator<T> : IModuleIterator<T> where T : Module
  {
  private T[] modules;
  private uint array_pointer = 0;
  
  /// <summary cref="IModuleIterator{T}.hasNext" />
  /// <seealso cref="IModuleIterator{T}.hasNext" />
  public bool hasNext()
  {
  return array_pointer < modules.Length;
  }
  
  /// <summary cref="IModuleIterator{T}.next" />
  /// <seealso cref="IModuleIterator{T}.next" />
  public T next()
  {
  return modules[array_pointer++];
  }
  
  /// <summary>
  /// For internal use only: Initializes a new instance of
  /// the <see cref="ModuleIterator{T}"/> class with the
  /// given modules.
  /// </summary>
  /// <remarks>
  /// As the original list is subject to change an
  /// iterator is created by passing an array of the
  /// currently existing modules.
  /// </remarks>
  /// <seealso cref="IModuleConverter{T}.iterator"/>
  /// <param name="modules">Modules which should be
  /// traverse to</param>
  internal ModuleIterator(T[] modules)
  {
  if (modules == null)
  throw new ArgumentException("Argument null", "T[] modules");
  this.modules = modules;
  }
  
  }
  
  }
  
  You see. An iterator pattern. There's an interface which demands for methods. And there's an class which implements those methods. I really like to have a link to the derived interface or a copy of the comments within the ready chm file. But not this again:
  
  

  [Missing <summary> documentation for T:CMF.enviroment.converter.ModuleIterator`1]

  Even the methods hasNext() and next() have no comments:

  [Missing <summary> documentation for M:CMF.enviroment.converter.ModuleIterator`1.hasNext]

  [Missing <summary> documentation for M:CMF.enviroment.converter.ModuleIterator`1.next]

  Thank you for further information.
  

  Marcel
  

  
  
  

• database_mentor

  Thanks, Eric.
  
  Ok, the "missing documentation" messages are gone. And I agree. It really seems that the "inheritance" of comments might not be possible. I'm not not sure and please don't beat me for my guessing. ;-)
  
  By the way the notation
  <summary cref="..." />
  was seen by me here:
  http://msdn2.microsoft.com/en-us/library/acd0tfbe.aspx
  
  Might be I misunderstood it. But let's wait for Anand's answer.
  
  Thank you guys
  Marcel
  
  
  

• JimBobJoe

  Anand can correct me if I'm wrong but the <summary> tag doesn't support a "cref" attribute so I doubt the Sandcastle transforms are even looking for it. I wasn't aware that Sandcastle supported inherited documentation either. With regard to the "missing documentation" messages from the help file builder, if it sees an empty <summary> tag, it adds the message. For the time being, you'll just need to set the ShowMissingSummary project option to false. The same would apply for any of the other ShowMissing* options for stuff like inherited parameters and return values. If the summaries don't show up after setting those options to false, then the Sandcastle transformations aren't pulling in the inherited comments.

  Eric

  
  

• Mike Chapman

  Marcel,

  Please see if you have the code in the right place as shown below:

  Sandcastle.config

  <!-- Copy in comments -->

  <component type="Microsoft.Ddue.Tools.CopyFromIndexComponent" assembly="%DXROOT%\ProductionTools\BuildComponents.dll">

  <index name="comments" value="/doc/members/member" key="@name" cache="100">

  <data files="comments.xml" />

  <data files="%SystemRoot%\Microsoft.NET\Framework\v2.0.50727\*.xml" />

  </index>

  <copy name="comments" source="*" target="/document/comments" />

  </component>

  <component type="Microsoft.Ddue.Tools.CopyFromIndexComponent" assembly="%DXROOT%ProductionTools\BuildComponents.dll">

  <copy name="comments" key="string(/document/reference/implements/type/@api)" source="summary" target="/document/reference/implements" />

  </component>

  <!-- Copy in reflection data and comments for members -->

  <component type="Microsoft.Ddue.Tools.ForEachComponent" assembly="%DXROOT%\ProductionTools\BuildComponents.dll">

  <variable expression="/document/reference/elements/element/@api" />

  <components>

  <component type="Microsoft.Ddue.Tools.IfThenComponent" assembly="%DXROOT%\ProductionTools\BuildComponents.dll">

  <if condition="not(/document/reference/elements/element[@api=$key]/*)" />

  <then>

  <component type="Microsoft.Ddue.Tools.CopyFromIndexComponent" assembly="%DXROOT%\ProductionTools\BuildComponents.dll">

  <copy name="reflection" source="*[not(local-name()='elements')]" target="/document/reference/elements/element[@api=$key]" />

  </component>

  </then>

  </component>

  <component type="Microsoft.Ddue.Tools.CopyFromIndexComponent" assembly="%DXROOT%\ProductionTools\BuildComponents.dll">

  <copy name="comments" source="summary|overloads" target="/document/reference/elements/element[@api=$key]" />

  </component>

  </components>

  </component>

  Main_sandcastle.xsl:

  <xsl:template name="body">

  <!-- auto-inserted info -->

  <!-- <xsl:apply-templates select="/document/reference/attributes" /> -->

  <xsl:apply-templates select="/document/comments/preliminary" />

  <xsl:apply-templates select="/document/comments/summary" />

  <xsl:apply-templates select="/document/reference/implements/summary"/>

  Anand..

  
  
  
• Sandcastle: Comment references