Does the NamespaceDoc still work with version 1.9.6.0?

Mar 1, 2013 at 8:54 AM
Hi,

Does the NamespaceDoc still work with version 1.9.6.0?

I created the following,
using System.Runtime.CompilerServices;

namespace MyProject
{
    /// <summary>
    /// The <see cref="MyProject"/> namespace is the main namespace for MyProject.
    /// </summary>
    [CompilerGeneratedAttribute]
    internal class NamespaceDoc
    {
    }
}
But I'm still getting,
Warn: ShowMissingComponent: [N:MyProject] Missing <summary> documentation
Thanks.
Coordinator
Mar 1, 2013 at 3:13 PM
Yes, they are still working and nothing has changed. The typical causes are that the XML comments file is not up to date or that you are using a configuration (Debug/Release) that hasn't been built and doesn't contain the new comments. The log file will tell you which XML comments files were used and you can check them to see if the NamespaceDoc comments are in there.

Eric
Mar 2, 2013 at 1:19 AM
Hi,

Yes, what you said is what actually happened. However, how does it obtain the location of the XML file? In the project files, all of the XML Documentation path is set to "......\doc\MyProject.XML" but instead shfb looks for "......\bin\Release\MyProject.XML". The output path of the project is "......\bin\Release\" though.

Thanks.
Coordinator
Mar 2, 2013 at 2:53 AM
Edited Mar 2, 2013 at 2:54 AM
It uses the Visual Studio project's DocumentationFile property and, if relative combines it with the project's path unless OutDir has been defined in which case it combines it with that path. If fully qualified, it will use it as is. Bear in mind that the DocumentationFile property is specific to each build so while you may have set it to "..\Doc\MyProject.xml" for the Debug build, you may not have done so for the release build and it may still be pointing to the default "..\bin\Release" folder in that configuration in your project.

Eric
Mar 4, 2013 at 2:49 AM
So, perhaps there is a bug in the path handling?

The Output path for the project is,
..\..\..\bin\Release\
and the XML documentation file path is,
..\..\..\doc\MyProject.XML
and shfb seems to generate the following path when copying the XML file,
C:\[project path]\..\..\..\bin\Release\MyProject.XML
Coordinator
Mar 4, 2013 at 7:13 PM
It would appear that MSBuild or the default target files have changed and OutDir is now always defined and defaults to the project output path if not explicitly defined elsewhere. As such it will always pull the comments file from the project's output path. However, that shouldn't be an issue as the compiler builds the comments file there and then copies it to the file specified by DocumentationFile. So, if your project is up to date, both files should be identical and contain the required comments.

Eric
Mar 5, 2013 at 12:59 AM
Hi,

Thanks for the confirmation. I guess you are right. The issue I'm having now might be related to my project file (or solution) but I couldn't seem to figure out what is causing it. It seems that after Visual Studio 2012 generates the XML file and copies it to the correct path, the original XML file in the project output path is replaced by a new XML file which only contain the project name. So, basically it's empty. However, if I rename the XML file to different name which is not the same as the project name, then the problem does not occur.

My project name is "MyProject", thus if I use the following for the XML documentation file path,
..\..\..\doc\MyProject.XML
It would generate the file and later empty it.

But if I change the name, say,
..\..\..\doc\MyProject2.XML
then, the problem would not arise.

So, in the end, the issue is not with shfb, but with Visual Studio 2012 itself. However, if you have any clue on what is happening, I would be grateful.

Btw, thank you very much for help out.
Coordinator
Mar 7, 2013 at 1:25 AM
I couldn't duplicate the behavior you describe with VS 2012. However, I have on occasion see VS 2010 do it with the SHFB project XML comments files and they end up with just an empty root element. Typically it is when I use the Build Solution option to just build the projects that are out of date. Using Rebuild Solution to force all projects to build always gets the comments files built.

Eric