Settings in DocProject (Presentation Style, External Sources)

Topics: Features, General Questions, Sandcastle
Sep 26, 2007 at 1:56 PM
Hello Dear

I've some question in relation to maybe SandCastle or DocProject.

First; How can i change the Style (Hama,Prototype,VS2005) of a DocProject-Project after creation?
Or, in which file are the "External Sources" and the "API Topic Management" saved, so that i can create a new project with the right style and import them?
--> The location of the container of the "External Sources" and the "API Topic Management" would be generally interesting for me, maybe its better for me to edit this files directly (depending on the given file-structure) instead with the UI.

Second; Is it possible to show "Missing XML Comment Tags", like in Sandcastle Help File Builder? (Or is this a general Sandcastle Setting, which should be generally available).

Thanks a lot.

Greetings
Cis
Sep 26, 2007 at 2:42 PM
Hi Cis,


First; How can i change the Style (Hama,Prototype,VS2005) of a DocProject-Project after creation?

This isn't recommended since DocProject imports all of the files and folders of the specific presentation that you choose when the project is first created. It also creates two sandcastle.config files by copying the original and then updates them to use the local Presentation folder instead of the original, among other changes. Other files in the Presentation folder are different depending upon the style, so if you were to attempt changing the style you'd have to import the entire Presentation folder from the new style. There's probably other things that would need to be done as well but I really don't remember off-hand since this isn't even a procedure that I've tried myself :)


Or, in which file are the "External Sources" and the "API Topic Management" saved, so that i can create a new project with the right style and import them?

External sources are saved in the project file itself. Open the project file and find the UserProperties element (near the bottom) and just copy the entire ExternalSources attribute into the new project file's UserProperties element.

The API Topic Management dialog stores content in two different places. Documentation created on the Xml Comments tab is stored in individual xml files in the Comments folder. This folder is created by DocProject so you can simply copy the entire folder into your new project, including the project.xml file, which contains all of your namespace comments. The Topic Filter data is stored in Sandcastle's MRefBuilder.config file, which you can safely import into your new project as well. The file is located in the Presentation\Style\Configuration folder of your DocProject.


The location of the container of the "External Sources" and the "API Topic Management" would be generally interesting for me, maybe its better for me to edit this files directly (depending on the given file-structure) instead with the UI.

Using the External Sources dialog is recommended since you must unload the project to change its content, although DocProject can write to the file without unloading it :) The API Topic Management dialog simply writes to the files for you and I prefer to use the UI when possible, although that's just my personal preference. If you prefer to edit the API filter in the MRefBuilder.config file manually, or write Xml Documentation manually you certainly can, but it also means that you have to manage the files yourself and make sure that the XML structure is correct.


Second; Is it possible to show "Missing XML Comment Tags", like in Sandcastle Help File Builder? (Or is this a general Sandcastle Setting, which should be generally available).

I have not implemented a missing comments feature, and I probably won't in the future either. I prefer not to use auto-generated documentation as it commonly provides no value to end-users other than to fill-in-the-blanks. IMO, end-users are better off knowing that I didn't write any documentation instead of assuming that I wrote something so simple a computer could figure it out ;)

Anyway, you should check to see if Eric (the author of SHFB) has provided this feature as a custom build component for Sandcastle. I think he's deployed some stand-alone build components and that may be one of them.

- Dave
Sep 26, 2007 at 3:14 PM
Edited Sep 26, 2007 at 3:15 PM

davedev wrote:
Hi Cis,

I have not implemented a missing comments feature, and I probably won't in the future either. I prefer not to use auto-generated documentation as it commonly provides no value to end-users other than to fill-in-the-blanks. IMO, end-users are better off knowing that I didn't write any documentation instead of assuming that I wrote something so simple a computer could figure it out ;)


I absolutely understand what you mean :-) We would have used this feature for our developers.

In my situation, there are 5 Main-Namespaces (with near hundreds of subnamespaces) and for this documentation we need about 20 classes, interfaces and enumerations (all without constructors). So it is a small set of the whole code.

This small documented set is for our consultants (because they wright something like "C# script" like ABAP from SAP). So, if a not existing xml tag would be markable we (the developers) could document it (because this field is maybe clear for a c# developer, but not for a consultant). --> Text would be in big,bold red font "Developer, comment me!" ;-)

And because we need only a small subset of the linked project, it would be hard to enable this as "code analysis" because this is project wide and we don't want to document all code (only this one which is interesting for our consultant's). So it would be more a help for our developers than for the final documentation himself. But it is not that important.

So, thanks a lot for your very good explanation!

sincerely yours
Sep 26, 2007 at 3:25 PM
Hi Cis,

Ok, I get it. To be perfectly honest, I thought that the "Missing comments" feature actually attempted to write useful documentation - not just a "Missing!" comment. And I can see how that might be useful in your particular situation.

Definitely check to see if Eric has made a stand-alone build component that can do what you want. If not, you can add it as a feature request to DocProject and I'll consider writing a build component for it in the future.

Thanks,
Dave
Sep 27, 2007 at 9:18 AM
Edited Oct 4, 2007 at 9:18 AM
Real nice;

As you explained, i knew that this feature was in helpfilebuilder but thought it was only dedicated to the SHFB project, not to sandcastle standalone.
I read about this feature in the HelpFileBuilder-Help.

The only thing to do is add the following xml to the

"..\Presentation\Style\Configuration\sandcastle.help1x.config" File (right before the TransformComponent XML Element)


<!-- Show missing documentation component configuration. This must
appear before the TransformComponent. -->
<component type="SandcastleBuilder.Components.ShowMissingComponent"
assembly="C:\SandcastleBuilder\SandcastleBuilder.Components.dll">
<!-- All elements are optional. -->

<!-- Auto-document constructors (true by default) -->
<AutoDocumentConstructors value="true" />

<!-- Show missing param tags (true by default) -->
<ShowMissingParams value="true" />

<!-- Show missing remarks tags (false by default) -->
<ShowMissingRemarks value="false" />

<!-- Show missing returns tags (true by default) -->
<ShowMissingReturns value="true" />

<!-- Show missing summary tags (true by default) -->
<ShowMissingSummaries value="true" />

<!-- Show missing value tags (false by default) -->
<ShowMissingValues value="false" />

<!-- Show missing namespace comments (true by default) -->
<ShowMissingNamespaces value="true" />
</component>


Exactly what i wanted, thanks a lot!
Sep 27, 2007 at 4:46 PM
Cool, thanks for the info.