New Post: Unable to build project to obtain API information

February 27, 2013, 4:53 pm

≫ Next: New Post: BE0071 - Error

≪ Previous: New Post: Unable to build project to obtain API information

$

0

0

The latest release does support .winmd files as documentation sources with the above noted issues. I'll need a proper example to diagnose any problems such as missing comments. If you can e-mail me a small example that isn't working, I'll look into it. My e-mail address is in the About box in the standalone GUI and in the footer of the pages in the help file.

Eric

---

New Post: BE0071 - Error

February 28, 2013, 6:53 am

≫ Next: New Post: Tracking error/warn count in log?

≪ Previous: New Post: Unable to build project to obtain API information

$

0

0

Eric,
It is a win server 2008 and visual studio was not installed.
Thank you for offering to fix your package but as far as i am concerned my problem is solved.
Franck

New Post: Tracking error/warn count in log?

February 28, 2013, 4:38 pm

≫ Next: New Post: Does the NamespaceDoc still work with version 1.9.6.0?

≪ Previous: New Post: BE0071 - Error

$

0

0

I would like to track the number of warnings shown in the LastBuild.log file, as I have noticed a large number of links to conceptual or API pages breaking when the developers in my team change their code/ make things internal; or if I decide to retire a conceptual topic on a Friday afternoon and forget to check the API source code for links.

If I could see a total warning count in the log, and this number went up, I would instantly know that something had changed that needs to be fixed.

At the moment, I open the log file and check each individual warning and error. This helps me track down these sorts of problems one by one, but I don't generally know that they exist until I stumble across a link somewhere in the docs that has mysteriously stopped working, and turned into bold text.

Is there an easy way for me to add a total warning count to the log file?

New Post: Does the NamespaceDoc still work with version 1.9.6.0?

March 1, 2013, 1:54 am

≫ Next: New Post: WinRT project, public sealed classes are not visible in documentation

≪ Previous: New Post: Tracking error/warn count in log?

$

0

0

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.

New Post: WinRT project, public sealed classes are not visible in documentation

March 1, 2013, 7:08 am

≫ Next: New Post: WinRT project, public sealed classes are not visible in documentation

≪ Previous: New Post: Does the NamespaceDoc still work with version 1.9.6.0?

$

0

0

I have WinRT project, produce .winmd on output, x86, written on C#. Also produce .xml documentation.

Problem is simple - public structs visible, public sealed classes (WinRT API require to make them sealed) - not visible.

Latest, 1.9.6.0 used.

New Post: WinRT project, public sealed classes are not visible in documentation

March 1, 2013, 7:59 am

≫ Next: New Post: Does the NamespaceDoc still work with version 1.9.6.0?

≪ Previous: New Post: WinRT project, public sealed classes are not visible in documentation

$

0

0

The latest release does support .winmd files as documentation sources with issues noted in this thread. I'll need a proper example to diagnose any problems such as missing comments or members. If you can e-mail me a small example that isn't working, I'll look into it. My e-mail address is in the About box in the standalone GUI and in the footer of the pages in the help file.

Eric

New Post: Does the NamespaceDoc still work with version 1.9.6.0?

March 1, 2013, 8:13 am

≫ Next: New Post: Tracking error/warn count in log?

≪ Previous: New Post: WinRT project, public sealed classes are not visible in documentation

$

0

0

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

New Post: Tracking error/warn count in log?

March 1, 2013, 8:14 am

≫ Next: New Post: Does the NamespaceDoc still work with version 1.9.6.0?

≪ Previous: New Post: Does the NamespaceDoc still work with version 1.9.6.0?

$

0

0

It'll need to be added to the build engine. I can probably make the change for the next release.

Eric

---

New Post: Does the NamespaceDoc still work with version 1.9.6.0?

March 1, 2013, 6:19 pm

≫ Next: New Post: Does the NamespaceDoc still work with version 1.9.6.0?

≪ Previous: New Post: Tracking error/warn count in log?

$

0

0

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.

New Post: Does the NamespaceDoc still work with version 1.9.6.0?

March 1, 2013, 7:53 pm

≫ Next: New Post: WinRT project, public sealed classes are not visible in documentation

≪ Previous: New Post: Does the NamespaceDoc still work with version 1.9.6.0?

$

0

0

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

New Post: WinRT project, public sealed classes are not visible in documentation

March 2, 2013, 2:18 am

≫ Next: Closed Issue: Web keyword index has incomplete title for subnodes [32262]

≪ Previous: New Post: Does the NamespaceDoc still work with version 1.9.6.0?

$

0

0

Sent.

Closed Issue: Web keyword index has incomplete title for subnodes [32262]

March 2, 2013, 6:17 pm

≫ Next: Updated Wiki: Future Enhancements and Features

≪ Previous: New Post: WinRT project, public sealed classes are not visible in documentation

$

0

0

The title of subnodes should include more details to be able to tell them apart. For instance, if I have several types that define the Addition operator, I end up with something like the following:
 
Addition
- operator
- operator
- operator
...
 
There is no way to tell the difference between the subnodes... Each title should be something like "Foo.Addition operator", "Bar.Addition operator", etc.
Comments: The fix for this was in two parts:
- Changed the XSL transformations to output the qualified member name in the topic's page title HTML element.
- Modified the HTML extract tool to use the topic title or TOC title depending on the context and also had it group the index keywords by title such that the elements with a common title like "Addition Operator" use a single root entry with each of the individual topics as sub-entries. The sub-entries use the qualified name title from the topic thus making them distinct and each clearly indicates to which class it belongs.

The change to the HTML title element does have the side-effect of causing member titles in the MS Help Viewer TOC to be qualified with the class name as Help Viewer no longer supports a TOCTitle metadata attribute like Help 2 did. Help for base framework classes exhibits the same behavior so this appears to be by design.

Updated Wiki: Future Enhancements and Features

March 2, 2013, 6:20 pm

≫ Next: Updated Wiki: Future Enhancements and Features

≪ Previous: Closed Issue: Web keyword index has incomplete title for subnodes [32262]

$

0

0

Below is a list of future enhancements and features for the Sandcastle tools and the Sandcastle Help File Builder. No planned release dates have been set for these items. Each item may be implemented all at once or a little at a time depending on its scope and complexity. If you'd like to comment on any of these, please do so on the related work item page (see the links below) or, to make additional suggestions, please start a new discussion.

Sandcastle Tools

• Expose as public many of the internal BuildAssembler-related classes used for stuff like target info. That will make it easier to reuse the classes in third-party components and third-party components derived from existing Sandcastle build components. http://shfb.codeplex.com/workitem/33223

• Investigate improving the performance of BuildAssembler. Things to consider:
  • Sharing information between build components that use the same info rather than loading it again.
  • Use pre-built cache files to save on initialization time.
  • Use pre-built cache files to load information on demand to reduce memory usage.
  • Longer term, investigate the possibility of having BuildAssembler build topics in parallel. That would require that all build components in the stack are thread safe though.
  • http://shfb.codeplex.com/workitem/33224

• Remove the remaining branding stuff from the VS2010 style and SHFB. Branding support seemed like a good idea but with the changes in HV2, that is not the case and it has proven to be more trouble than it was worth. Sandcastle output requires some level of self-branding as non-self-branded content would not be able to use any custom scripts and stylesheets used for things like code colorization or other such features added by custom build components that rely on them. Supporting alternate branding packages doesn't seem to make sense as that's what presentation styles are for. In short, it makes better sense to treat all Sandcastle presentation styles as self-branded and remove the use of branding packages. http://shfb.codeplex.com/workitem/33225

• Investigate whether or not a folder name can safely be introduced into the GUID and hashed member name naming methods to reduce the number of files in the root HTML output folder. http://shfb.codeplex.com/workitem/33058

• Create an Open XML presentation style with any related build components that outputs the help as an Open XML document. The resulting output document should be readily convertible to other formats such as PDF without having to add additional presentation styles or conversion tools to Sandcastle. http://shfb.codeplex.com/workitem/33226

• Create an MSDN Lightweight presentation style for website output that mimics the current MSDN website pages with the TOC info in each page. http://shfb.codeplex.com/workitem/33227

• Perhaps update the tools to enable them to run as MSBuild tasks. Also, there are a lot of obsolete files that should be removed (i.e. Microsoft-specific configuration files that serve no apparent useful purpose). If possible, update the Sandcastle tools and build scripts to utilize a modified version of the presentation style definition file. http://shfb.codeplex.com/workitem/33373

• As time permits, add more information to the Sandcastle tools help file that describes the various tools and how they work. http://shfb.codeplex.com/workitem/33228

Sandcastle Help File Builder

• Update MRefBuilder to support the Visibility options from SHFB directly. This would be more efficient as the unwanted members could be stripped during the reflection phase rather than after the fact which requires loading the reflection data XML file. http://shfb.codeplex.com/workitem/33231

• Add a transformation to match the SHFB hashed member naming option method. That would get rid of the need to load the reflection file in SHFB after applying the doc model transformation. http://shfb.codeplex.com/workitem/33233

Updated Wiki: Future Enhancements and Features

March 2, 2013, 6:22 pm

≫ Next: New Post: Does the NamespaceDoc still work with version 1.9.6.0?

≪ Previous: Updated Wiki: Future Enhancements and Features

$

0

0

Below is a list of future enhancements and features for the Sandcastle tools and the Sandcastle Help File Builder. No planned release dates have been set for these items. Each item may be implemented all at once or a little at a time depending on its scope and complexity. If you'd like to comment on any of these, please do so on the related work item page (see the links below) or, to make additional suggestions, please start a new discussion.

Sandcastle Tools

• Expose as public many of the internal BuildAssembler-related classes used for stuff like target info. That will make it easier to reuse the classes in third-party components and third-party components derived from existing Sandcastle build components. http://shfb.codeplex.com/workitem/33223

• Investigate improving the performance of BuildAssembler. Things to consider:
  • Longer term, investigate the possibility of having BuildAssembler build topics in parallel. That would require that all build components in the stack are thread safe though.
  • http://shfb.codeplex.com/workitem/33224

• Remove the remaining branding stuff from the VS2010 style and SHFB. Branding support seemed like a good idea but with the changes in HV2, that is not the case and it has proven to be more trouble than it was worth. Sandcastle output requires some level of self-branding as non-self-branded content would not be able to use any custom scripts and stylesheets used for things like code colorization or other such features added by custom build components that rely on them. Supporting alternate branding packages doesn't seem to make sense as that's what presentation styles are for. In short, it makes better sense to treat all Sandcastle presentation styles as self-branded and remove the use of branding packages. http://shfb.codeplex.com/workitem/33225

• Investigate whether or not a folder name can safely be introduced into the GUID and hashed member name naming methods to reduce the number of files in the root HTML output folder. http://shfb.codeplex.com/workitem/33058

• Create an Open XML presentation style with any related build components that outputs the help as an Open XML document. The resulting output document should be readily convertible to other formats such as PDF without having to add additional presentation styles or conversion tools to Sandcastle. http://shfb.codeplex.com/workitem/33226

• Create an MSDN Lightweight presentation style for website output that mimics the current MSDN website pages with the TOC info in each page. http://shfb.codeplex.com/workitem/33227

• Perhaps update the tools to enable them to run as MSBuild tasks. Also, there are a lot of obsolete files that should be removed (i.e. Microsoft-specific configuration files that serve no apparent useful purpose). If possible, update the Sandcastle tools and build scripts to utilize a modified version of the presentation style definition file. http://shfb.codeplex.com/workitem/33373

• As time permits, add more information to the Sandcastle tools help file that describes the various tools and how they work. http://shfb.codeplex.com/workitem/33228

Sandcastle Help File Builder

• Update MRefBuilder to support the Visibility options from SHFB directly. This would be more efficient as the unwanted members could be stripped during the reflection phase rather than after the fact which requires loading the reflection data XML file. http://shfb.codeplex.com/workitem/33231

• Add a transformation to match the SHFB hashed member naming option method. That would get rid of the need to load the reflection file in SHFB after applying the doc model transformation. http://shfb.codeplex.com/workitem/33233

New Post: Does the NamespaceDoc still work with version 1.9.6.0?

March 3, 2013, 7:49 pm

≫ Next: Commented Issue: VS2012 crashes when I open the Test Explorer and the SHFB extension is enabled [33494]

≪ Previous: Updated Wiki: Future Enhancements and Features

$

0

0

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

---

Commented Issue: VS2012 crashes when I open the Test Explorer and the SHFB extension is enabled [33494]

March 4, 2013, 9:43 am

≫ Next: Created Issue: VS extension: "About..." should not be in project context menu. [33839]

≪ Previous: New Post: Does the NamespaceDoc still work with version 1.9.6.0?

$

0

0

HiI don't know if it's at your side to do something or not, but when i have installed the latest SHFB (1.9.5.0) and enabled the extension, VS 2012 crashes when I try to open the Test Explorer. When the extension is disabled, the Test Explorer could be opened.See also here:https://connect.microsoft.com/VisualStudio/feedback/details/762552/vs-2012-crashes-when-opening-test-explorer
Comments: ** Comment from web user: pfgoncalves **

I have the same problem, visual studio 2012 Premium Update 1 crashes if I have a SandCastle project loaded, the Test Explorer window open and try to debug.
To temporary solve the issue I close the Test Explorer Window or unload the sandcastle project.
Please fix this.

Created Issue: VS extension: "About..." should not be in project context menu. [33839]

March 4, 2013, 10:36 am

≫ Next: Created Issue: Make build fail early on easy to detect errors. [33840]

≪ Previous: Commented Issue: VS2012 crashes when I open the Test Explorer and the SHFB extension is enabled [33494]

$

0

0

In Visual Studio, the context menu for a project is already very full. 'About Sandcastle Help File Builder' really doesn't belong there.

Created Issue: Make build fail early on easy to detect errors. [33840]

March 4, 2013, 10:43 am

≫ Next: New Post: Does the NamespaceDoc still work with version 1.9.6.0?

≪ Previous: Created Issue: VS extension: "About..." should not be in project context menu. [33839]

$

0

0

For large projects, the build process can take a long time (15 minutes or more). Some errors, like a badly configured build component, can show up minutes into the build.

I would like to see a build step early on in the build that checks for such easy to detect errors and causes the build to fail in seconds, not minutes.

New Post: Does the NamespaceDoc still work with version 1.9.6.0?

March 4, 2013, 12:13 pm

≫ Next: Commented Issue: Make build fail early on easy to detect errors. [33840]

≪ Previous: Created Issue: Make build fail early on easy to detect errors. [33840]

$

0

0

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

Commented Issue: Make build fail early on easy to detect errors. [33840]

March 4, 2013, 12:24 pm

≫ Next: New Post: Does the NamespaceDoc still work with version 1.9.6.0?

≪ Previous: New Post: Does the NamespaceDoc still work with version 1.9.6.0?

$

0

0

For large projects, the build process can take a long time (15 minutes or more). Some errors, like a badly configured build component, can show up minutes into the build.

I would like to see a build step early on in the build that checks for such easy to detect errors and causes the build to fail in seconds, not minutes.
Comments: ** Comment from web user: EWoodruff **

Since it's the build component that determines whether or not the configuration is valid, there's really not much I can do earlier in the process. The next release will mitigate the issue somewhat as it now automatically opens the configuration dialog for the component if there is one when added to the project thus forcing you to accept the defaults or add missing info when you add the component to the project.