xml comments are not included in the output help file

Topics: General Questions
Apr 15, 2010 at 3:10 PM

All --

Please help.

I have a simple class, as follows...

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace DocProjectTest1
{
    /// <summary>
    /// This is a test class.
    /// </summary>
    public class Class1
    {
        /// <summary>
        /// This will get the long date string.
        /// </summary>
        /// <returns>This is the date.</returns>
        public string GetDateText()
        {
            return DateTime.Now.ToLongDateString();
        }
    }
}

...and I have a DocProject in the solution and everything builds...

...BUT...

...when I view the Help 2 output, the text in the XML comments is not included in the help file...

...and I am using DocProject out-of-the-box, with no customizations, so I am wondering by DocProject by default does not include XML comments, etc.

What did I miss in the process?

How do I tell DocProject to include the XML comments?

Please advise.

Thank you.

-- Mark Kamoski

Apr 15, 2010 at 4:58 PM
Edited Apr 15, 2010 at 5:00 PM

Hi Mark,

You have to enable XML documentation output for your project.

http://docproject.codeplex.com/wikipage?title=Sandcastle%20Help#xmldoc

- Dave

Apr 16, 2010 at 12:01 PM

Dave --

Oh yes, I forgot, to generate an XML comments file the setting is...

>Project, >Properties, >Build, >Output, >XmlDocumentationFile=Checked

...and that does the trick.

Thank you.

-- Mark Kamoski

Jan 11, 2011 at 5:49 PM
davedev wrote:

Hi Mark,

You have to enable XML documentation output for your project.

http://docproject.codeplex.com/wikipage?title=Sandcastle%20Help#xmldoc

- Dave

I've done this with my newest project and the XML comments still aren't showing up. I compared the settings with an older project and even though it doesn't have this setting enabled, it still includes the XML comments. The format in the code is correct as well.

What else am I missing here?

Jan 11, 2011 at 7:07 PM

After looking at the XML file, it is not adding the comments to the XML file. Just the default items are there. It's not pulling anything from my code. 

 

<?xml version="1.0" ?

- <doc>
- <assembly>
  <name>BenuHelp</name>
  </assembly>
- <members>
- <member name="T:BenuHelp.BuildProcess">
  <summary>Hooks into the DocProject build process for the project in which it's defined.</summary>
- <remarks>
- <para>
  This class must be registered with the DocProject in the
  <em>Active Projects</em>
  tools options page in order for DocProject to instantiate it during a help build.
  </para>
- <para>
  To cancel the build at any time call the
  <see cref="M:DaveSexton.DocProject.BuildContext.Cancel" />
  method. The build process will end after the current step is executed, unless the step is being executed in the background. In that case, it may end immediately.
  </para>
- <para>
  Note: Do not cache instances of the
  <see cref="T:DaveSexton.DocProject.BuildContext" />
  class. A new
  <see cref="T:DaveSexton.DocProject.BuildContext" />
  is created each time the project is built.
  </para>
  </remarks>
  </member>
- <member name="M:BenuHelp.BuildProcess.BuildStarting(DaveSexton.DocProject.BuildContext)">
  <summary>Called before the project's help build starts.</summary>
  <param name="context">Provides information about the build process.</param>
  </member>
- <member name="M:BenuHelp.BuildProcess.BeforeExecuteStep(DaveSexton.DocProject.Engine.IBuildStep,DaveSexton.DocProject.BuildContext)">
- <summary>
  Called before a
  <paramref name="step" />
  is executed during a help build.
  </summary>
- <param name="step">
  <see cref="T:DaveSexton.DocProject.Engine.IBuildStep" />
  implementation to be executed.
  </param>
  <param name="context">Provides information about the build process.</param>
- <returns>
  <b>true</b>
  indicates that the process should continue, otherwise,
  <b>false</b>
  indicates that the process should skip this step.
  </returns>
  </member>
- <member name="M:BenuHelp.BuildProcess.AfterExecuteStep(DaveSexton.DocProject.Engine.IBuildStep,DaveSexton.DocProject.BuildContext)">
- <summary>
  Called after a
  <paramref name="step" />
  has been executed during a help build.
  </summary>
- <param name="step">
  <see cref="T:DaveSexton.DocProject.Engine.IBuildStep" />
  implementation that was executed.
  </param>
  <param name="context">Provides information about the build process.</param>
  </member>
- <member name="M:BenuHelp.BuildProcess.BuildCompleted(DaveSexton.DocProject.BuildContext)">
  <summary>Called after the project's help build has finished.</summary>
- <remarks>
  The
  <see cref="M:DaveSexton.DocProject.BuildContext.Cancel" />
  method has no affect at this point in the build process. This method is the final step before the build statistics are displayed.
- <para>
  This method is always invoked if
  <see cref="M:BenuHelp.BuildProcess.BuildStarting(DaveSexton.DocProject.BuildContext)" />
  is invoked, regardless of whether an exception is thrown in any of the other methods,
  <see cref="M:DaveSexton.DocProject.BuildContext.Cancel" />
  has been called, or an exeception has been thrown by the build engine.
  </para>
- <para>
  To determine whether a help build failed or succeeded, examine the value of the
  <see cref="P:DaveSexton.DocProject.BuildContext.BuildState" />
  property.
  </para>
  </remarks>
  <param name="context">Provides information about the build process.</param>
  </member>
  </members>
  </doc>
Jan 11, 2011 at 7:50 PM
Edited Jan 11, 2011 at 7:51 PM

Hi,

That's the XML file for your DocProject project.  You need to enable XML documentation output for your project; I mean the project being documented.  Perhaps you misunderstood the instructions. :)

- Dave

Jan 11, 2011 at 8:07 PM

Okay, that's what I probably misunderstood, however, I have another problem, the DocProject External UI won't launch, I keep getting a program has stopped working message when I try to start it up. I uninstalled and reinstalled docproject thinking that would fix it, but it didn't.

Jan 11, 2011 at 8:47 PM

Hi,

No problem.

For your new issue, please start a new thread and include any related information, such as an exception and stack trace, that you can find in the Windows Event Viewer.  DocProject is the name of the Source.

- Dave