A CodeDoc XML project file is used to tell CodeDoc what C# source files to process, what additional topics to add, and other information related to a single CodeDoc "project". This section describes the CodeDoc XML project file format: each subsection below defines a specific XML node within the project file.
If you like, you can edit a CodeDoc XML project file within Microsoft Visual Studio. In this case, you can activate Visual Studio's IntelliSenseTM feature by pointing Visual Studio to CodeDoc'x XML schema definition file, CodeDoc.xsd.
CodeDoc includes two project files you can use as examples:
The general structure of a CodeDoc project file is as follows. Many elements are optional and many can be repeated—see the documentation of each element for more information.
| XML Outline |
|
<CodeDoc>
optionally, repeat <ReadSource>, <WriteDocumentation>,
<WriteFormattedCode>
|
Elements that are direct children of <CodeDoc> may be present in any order, and are executed in that order. So, for example, it doesn't make sense to use <ReadSource> after the corresponding <WriteDocumentation> since <ReadSource> specifies the source files used by <WriteDocumentation>.
Elements that are not direct children of <CodeDoc> must be present in the order shown above or in the Syntax section of the documentation for each element.
For an example of a CodeDoc project file, see Creating a CodeDoc XML Project File in the CodeDoc User Guide page.
The following sections are an alphabetical reference of CodeDoc project file XML elements.
(Optional, used within <WriteDocumentation> and <WriteFormattedCode>.) Specifies a node (table of contents entry) within a DocBrowser (previously created by a <CreateDocBrowser> element) that documentation topic Web pages or formatted source code Web pages will be added as child nodes.
| XML |
|
<AddToDocBrowser>
IndexLabelSuffix="..."
InitiallyExpand="..."
NodeId="...">
<ChangeTitle>...</ChangeTitle>
</AddToDocBrowser>
|
IndexLabelSuffix
(String, optional.) If specified, this string is appended to the automatically-generated index entries for Web pages generated by the parent <WriteDocumentation> or <WriteFormattedCode> element. For example, IndexLabelSuffix=" (Source Code)", when used on a <AddToDocBrowser> element within a <WriteFormattedCode> element, helps the reader distinguish documentation topics from source code topics. If IndexLabelSuffix is not specified, no suffix is added.
InitiallyExpand
(Enumeration, optional, default "None".) Specifies which table of contents entries to initially expand (as if "+" were clicked), as follows:
| Attribute | Description |
| InitiallyExpand="None" | No table of contents entries are expanded. |
| InitiallyExpand="Namespaces" | Only namespace table of contents entries are expanded. |
| InitiallyExpand="NamespacesAndTypes" | Namespace and type table contents entries are expanded. |
| InitiallyExpand="All" | All table contents entries are expanded. |
NodeId
(Identifier reference, required.) Specifies which DocBrowser node the generated pages will be added as a child of. This determines which DocBrowser the pages will be added to, and where in that DocBrowser's table of contents the new pages will appear. NodeId must correspond to the NodeId attribute of a previous <CreateDocBrowser>, <DocBrowserNode>, or <SourceFilesNode> element.
See <WriteDocumentation> and <WriteFormattedCode> for examples of how <AddToDocBrowser> is used.
(Optional, used within <CodeDoc>.) Contains the names of XML elements that are unknown to CodeDoc that can be used within C# XML comments without displaying a warning.
In a C# source file, in an XML comment, when an unknown XML element that's unknown to CodeDoc is encountered, the XML element is copied to the generated HTML, and a warning is displayed. The purpose of the warning is to assist the user in the case that the XML element is a misspelling—for example, "<par>" instead of "<pr>". However, if the XML element is used intentionally—for example, "<b>" to make text bold—the warning can be suppressed by placing the XML element name (e.g. "b") within the <AllowXmlElements> section of the project file.
<AllowXmlElements> contains one XML element name per line, without "<" or ">" symbols. Leading and trailing white space on each line is ignored.
| XML |
|
<AllowXmlElements>
element-name
element-name
...
</AllowXmlElements>
|
(None)
This example specifies that "<a>", "<b>", "<i>", and "<u>" may be used within C# XML comments without generating warnings.
| XML |
|
<AllowXmlElements>
a
b
i
u
</AllowXmlElements>
|
(Optional, used within <ReadSource>.) The text of this element specifies the name of the assembly (.dll or .exe) containing the source file(s) specified by the parent <ReadSource> element. This name is used only for display purposes: if provided, it's displayed on generated Web pages.
| XML |
| <Assembly>assembly-name</Assembly> |
(None)
See <WriteDocumentation> and <WriteFormattedCode> for examples of how <Assembly> is used.
(Optional, used within <AddToDocBrowser>.) Specifies that the title of namespace topic(s) generated by <WriteDocumentation> or <WriteFormattedCode> be changed.
The default title for a namespace topic is of the form "qualified-namespace-name Namespace". If you don't like that default, you can use <ChangeTitle> to change it. Each <ChangeTitle> element specifies a search-and-replace pair; each pair is applied to each namespace title generated by <WriteDocumentation> and <WriteFormattedCode>.
There is no similar CodeDoc feature for changing the titles of topics corresponding to members within namespaces.
| XML |
|
<ChangeTitle Regex="..." Replacement="..." /> |
Regex
(String, optional.) A .NET Framework regular expression specifying the text within an automatically generated namespace title which should be changed.
Replacement
(String, required.) The text to change to.
| XML |
|
<ChangeTitle Regex="MyApp.Foo Namespace" Replacement="MyApp API - Foo Namespace" /> <ChangeTitle Regex="MyApp.Bar Namespace" Replacement="MyApp API - Bar Namespace" /> |
(Optional, used within <CodeDoc>, multiple allowed.) Removes all source files from the documentation set. Files are not actually deleted—<ClearSources> simply undoes the effect of all prior <ReadSource> elements.
| XML |
| <ClearSources /> |
(None)
See <WriteDocumentation> and <WriteFormattedCode> for examples of how <ClearSources> is used.
(Required.) The root of the project file.
| XML |
|
<CodeDoc xmlns="urn:schemas-dwell-net:codedoc:project-file" SupportFilesPathFromExe="..."> <AllowXmlElements>...</AllowXmlElements>
<DefinedSymbols>...</DefinedSymbols>
<ExternalReferences>...</ExternalReferences>
<ClearSources>...</ClearSources>
<CreateDocBrowser>...</CreateDocBrowser>
<DeleteFilesInDirectory>...</DeleteFilesInDirectory>
<DocBrowserStaticPages>...</DocBrowserStaticPages>
<ReadSource>...</ReadSource>
<WriteDocumentation>...</WriteDocumentation>
<WriteFormattedCode>...</WriteFormattedCode>
</CodeDoc>
|
SupportFilesPathFromExe
(String, optional, default "SupportFiles".) The path to the directory containing CodeDoc DocBrowser support files (such as "_CodeDoc.css" and "_1px.gif). The path is relative to the directory containing CodeDoc.exe.
This example is the simplest—and most common—ussage of the <CodeDoc> element. SupportFilesPathFromExe is not specified. Nested XML elements are not shown in this example, since, of course, the majority of the project file is contained between <CodeDoc> and </CodeDoc>.
| XML |
|
<CodeDoc xmlns="urn:schemas-dwell-net:codedoc:project-file"> ...
</CodeDoc>
|
(Optional, used within <CreateDocBrowser>, <WriteDocumentation>, and <WriteFormattedCode>, multiple allowed.) Copies a specified file into a location that depends on which element <CopyFile> is being used within:
<CopyFile> is typically used to copy resource files, such as images, that are used by DocBrowser static pages (see <DocBrowserStaticPages>), into the directory created by CodeDoc.
| XML |
|
<CopyFile NewName="..." Path="..." TextToHtml="..." /> |
NewName
(String, optional.) The name to give the file when it is copied. If absent, the original name of the file is used.
Path
(String, required.) The path to the file to copy, relative to the directory containing the CodeDoc XML project file.
TextToHtml
(Boolean, optional, default "false".) If set to "true", the source file is treated as text which is converted to HTML that displays the same as the text except it has the "Mark of the Web" to allow it to be linked to from a file that also has the "Mark of the Web".
| XML |
| <CopyFile Path="Diagram.gif" /> |
(Optional, used within <CodeDoc>, multiple allowed.) Begins a new DocBrowser, which is an HTML frameset containing a table of contents, an index, and a frame for pages. Static pages, i.e. Web pages you write by hand, can be added to a DocBrowser using subsequent <DocBrowserStaticPages> elements. Dynamic (automatically generated) pages can be added to a DocBrowser using a subsequent <AddToDocBrowser> element within <WriteDocumentation> or <WriteFormattedCode> elements.
| XML |
|
<CreateDocBrowser BaseName="..." BasicFramesetFileName="..." FramesetFileName="..." LeftFrameWidth="..." MarkOfTheWeb="..." NodeId="..." PagesRelativePath="..." Path="..." Title="..." </CreateDocBrowser> |
BaseName
(String, optional, default "Default".) Determines the prefix for certain files written to the directory specified by PagesRelativePath. For example, if the default value, "Default", is used, the table of contents HTML file will be named "Default_Contents.htm", and the basic frameset (see BasicFramesetFileName) version will be named "BasicDefault_Contents.htm".
BasicFramesetFileName
(String, optional.) Where to write the DocBrowser basic frameset file. This is a path that's relative to the DocBrowser root directory (see Path). The basic frameset is a simple HTML frameset intended for use by browsers that may not fully support the DHTML features supported by Microsoft Internet Explorer. If BasicFramesetFileName isn't present, no basic frameset is generated by CodeDoc.
FramesetFileName
(String, optional.) Where to write the DocBrowser regular frameset file. This is a path that's relative to the DocBrowser root directory (see Path). The regular frameset is assumes Internet Explorer DHTML features. If FramesetFileName isn't present, no regular frameset is generated by CodeDoc.
LeftFrameWidth
(Integer, optional, default "300".) The initial width, in pixels, of the HTML frameset frame containing the table of contents and index.
MarkOfTheWeb
(Boolean, optional, default "true".) If set to "true" (the default), then the "Mark of the Web" is included on generated pages. The Mark of the Web enables pages to be loaded into Internet Explorer 6.0 without a security warning when the pages are on a local hard disk. However, if the Mark of the Web is included in a frameset page, frames cannot load any content except HTML pages that also have the Mark of the Web. So, for example, if you'd like to include a Microsoft Word document using <DocBrowserStaticPages>, you'll need to set MarkOfTheWeb to "false".
NodeId
(Identifier, required.) Defines the identifier of the root of this DocBrowser; for example, "TocRoot" (table of contents root). All items within a DocBrowser table of contents are children of the root node or children of child nodes, etc. The root node itself isn't visible—all children of the root node are top-level nodes in the table of contents. NodeId within <CreateDocBrowser> is referred to by <DocBrowserStaticPages NodeId="..."> and <AddToDocBrowser NodeId="..."> elsewhere in the CodeDoc project file.
PagesRelativePath
(String, optional.) The path to the DocBrowser pages directory, i.e. the directory into which DocBrowser dynamically-generated page files will be written. This is typically a subdirectory of the DocBrowser root directory (see Path), so that the user won't have to sift through hundreds or thousands of files in the root directory in order to find the frameset root file (i.e. the file they open to view the documentation). This path is relative to the DocBrowser root directory (see Path); If PagesRelativePath is not specified, the DocBrowser pages directory is the same as the DocBrowser root directory.
Path
(String, required.) The path to the DocBrowser root directory, i.e. the directory into which frameset root files will be written. For example, if FramesetFileName is "Documentation.htm", then CodeDoc will write a "Documentation.htm" file into the DocBrowser root directory; when the user opens this file, they will see the the generated documentation, including a table of contents and index. This path is relative to the directory containing the CodeDoc project file. This directory is created if it doesn't exist.
Title
(String, optional.) The title that's displayed in the browser title bar. If absent, the value of BaseName is used.
| XML |
|
<CreateDocBrowser
BasicFramesetFileName="BasicBrowser.htm"
FramesetFileName="Documentation.htm"
LeftFrameWidth="290"
MarkOfTheWeb="true"
NodeId="TocRoot"
PagesRelativePath="Pages"
Path="Drop"
Title="MyApp User Guide & API Reference" />
|
(Optional, used within <CodeDoc>.) Contains the names
of C# preprocessor symbols which will be treated as defined (as if #define were
used) when C# files are parsed. This determines which code is excluded from documentation
topics, which is displayed in gray text in formatted source code, etc.
<DefinedSymbols> contains one preprocessor element name per line. Leading and trailing white space on each line is ignored.
| XML |
|
<DefinedSymbols>
preprocessor-symbol
preprocessor-symbol
...
</DefinedSymbols>
|
(None)
This example specifies that "DEBUG" and "FOO" preprocessor symbols are treated as defined,
as if #define DEBUG and #define FOO appeared at the top of all .cs
files.
| XML |
|
<DefinedSymbols>
DEBUG
FOO
</DefinedSymbols>
|
(Optional, used within <CodeDoc>, multiple allowed.) Deletes all files within a given directory. Does not delete the directory itself, or subdirectories, or files within subdirectories.
<DeleteFilesInDirectory> is typically used to delete the contents of the the DocBrowser root directory and pages directories, specified by the Path and PagesRelativePath attributes, respectively, of the <CreateDocBrowser> element, or the directory specified by the Path attribute of <WriteDocumentation> or <WriteFormattedCode>, before file are generated into those directories. This ensures that, if you run CodeDoc multiple times, changing source files between each run, you won't end up with outdated "leftover" files in any of these directories.
| XML |
| <DeleteFilesInDirectory Path="..." /> |
Path
(String, required.) The path to the directory to delete, relative to the directory containing the CodeDoc XML project file.
| XML |
|
<DeleteFilesInDirectory Path="Drop" /> <DeleteFilesInDirectory Path="Drop\Pages" /> |
(Optional, used within <DocBrowserStaticPages> and <SourceFilesNode>, and nested within other <DocBrowserNode> elements. Multiple allowed.) Specifies a Web page to add to a DocBrowser that was created by a previous <CreateDocBrowser> element. If MarkOfTheWeb="false" was specified in that <CreateDocBrowser> element, the Web page can be any file type (for example, a Microsoft Word document) that can be hosted within a browser, otherwise the Web page must be an HTML page that has the "Mark of the Web" in it.
If the Web page refers to external resources such as images, you can copy those files into the DocBrowser pages directory using the <CopyFile> element.
By default, no entry for this Web page is added to the DocBrowser index (i.e. the Index tab). Use one or more nested <IndexEntry> elements to add index entries.
If you'd like this Web page to contain nested Web pages within the DocBrowser table of contents (i.e. click the "+" beside this page's title in the table of contents to see the nested Web pages), included nested <DocBrowserNode> elements within this one.
| XML |
|
<DocBrowserNode InitiallyExpanded="..." NewFileName="..." NodeId="..." Path="..." Title="..."> <IndexEntry>...</IndexEntry>
<DocBrowserNode>...</DocBrowserNode>
</DocBrowserNode>
|
InitiallyExpanded
(Boolean, optional, default "false".) If "true", and if this <DocBrowser> node has nested <DocBrowser> nodes, the parent node is "expanded", as if the "+" beside the node were clicked, when the table of contents is initially displayed.
NewFileName
(String, optional.) The name to give the file when it is copied. If absent, the original name of the file is used.
NodeId
(Identifier, optional.) Specifies which DocBrowser node the Web page specified by this DocBrowserNode element will be added as a child of. This determines which DocBrowser the page will be added to, and where in that DocBrowser's table of contents the new page will appear. NodeId must correspond to the NodeId attribute of a previous <CreateDocBrowser>, <DocBrowserNode>, or <SourceFilesNode> element.
Path
(String, required.) The path to the file (Web page) to copy, relative to the directory containing the CodeDoc XML project file.
Title
(String, optional.) The title to use for this Web page within the table of contents. If not specified, the page's base file name (without an extension) is used.
See <DocBrowserStaticPages> and <SourceFilesNode> for examples of how <DocBrowserNode> is used.
(Optional, used within <CodeDoc>, multiple allowed.) Adds static Web pages (i.e. pages not generated by CodeDoc) to a DocBrowser that was created by a <CreateDocBrowser> element earlier in the CodeDoc XML project file.
The Web pages to add are specified by nested <CodeDoc> elements.
| XML |
|
<DocBrowserStaticPages NodeId="..."> <DocBrowserNode>...</DocBrowserNode>
</DocBrowserStaticPages>
|
NodeId
(Identifier reference, required.) Specifies which DocBrowser node the static Web pages will be added as a child of. This determines which DocBrowser the page will be added to, and where in that DocBrowser's table of contents the new pages will appear. NodeId must correspond to the NodeId attribute of a previous <CreateDocBrowser>, <DocBrowserNode>, or <SourceFilesNode> element.
The following example adds four root-level pages to a DocBrowser, assuming a previous <CreateDocBrowser> element with a NodeId="TocRoot" attribute. The third page, ProjectFile.htm, is nested under the second page, UserGuide.htm.
| XML |
|
<DocBrowserStaticPages NodeId="TocRoot">
<DocBrowserNode
Title="Introduction"
Path="DocFiles\Default.htm">
<IndexEntry>Introduction</IndexEntry>
</DocBrowserNode>
<DocBrowserNode
Title="MyApp User Guide"
Path="DocFiles\UserGuide.htm">
<IndexEntry>MyApp User Guide</IndexEntry>
<IndexEntry>User Guide</IndexEntry>
<DocBrowserNode
Title="MyApp Project File"
Path="DocFiles\ProjectFile.htm">
<IndexEntry>MyApp Project File</IndexEntry>
<IndexEntry>Project File</IndexEntry>
</DocBrowserNode>
</DocBrowserNode>
<DocBrowserNode
</DocBrowserStaticPages>
Title="MyApp API - Overview"
Path="DocFiles\ApiOverview.htm">
<IndexEntry>MyApp API - Overview</IndexEntry>
<IndexEntry>API Overview</IndexEntry>
</DocBrowserNode>
|
(Optional, used within <ReadSource>, multiple allowed.) Causes <ReadSource> to exclude C# source files that match a specified regular expression.
| XML |
| <ExcludeFilePaths Regex="..." /> |
Regex
(String, required.) A .NET Framework regular expression. Any C# source files that would otherwise have been read by the parent <ReadSource> element is excluded if its full path matches this expression.
See <WriteDocumentation> and <WriteFormattedCode> for examples of how <ExcludeFilePaths> is used.
(Optional, used within <CodeDoc>.) Specifies member
references for which warnings should be suppressed. For example, if a documented method has a
return type of List<string>, CodeDoc will issue a warning saying that the
reference to List<string> could not be resolved, since (of course) the type
List is defined by the .NET Framework. To suppress this warning, include a
List<> within the <ExternalReferences> section.
Note the use of angle brackets in this example—List<>—indicating that we're referring to the List template type with one type parameter. If we were referring to Dictionary, which has two type parameters, we'd use Dictionary<,>.
The following C# built-in types are never treated as unresolved external reference, so they
don't need to be included in the <ExternalReferences> section:
bool, byte, char, decimal,
double, fixed, float, int,
long, object, sbyte, short,
string, uint, ulong, ushort,
void.
| XML |
|
<ExternalReferences>
reference
reference
...
</ExternalReferences>
|
(None)
As shown in this example, you can use the XML CDATA construct to avoid having to represent angle brackets as < and <.
| XML |
|
<ExternalReferences>
<![CDATA[
ArgumentException
Dictionary<,>
FileNotFoundException
IEnumerable<>
IEnumerator<>
IList<>
InvalidOperationException
KeyValuePair<,>
List<>
Regex
StringBuilder
System.Collections.IEnumerator
TextReader
TextWriter
Type
WaitHandle
Xml
XmlException
XmlReader
]]>
</ExternalReferences>
|
(Optional, used within <DocBrowserNode>, multiple allowed.) The text of this element specifies the title of an entry that will be added to the DocBrowser index. When that entry is clicked the parent <DocBrowserNode> will be displayed.
| XML |
| <IndexEntry Bookmark="...">title</IndexEntry> |
Bookmark
(String, optional.) If specified, then if the user selects the index entry specified by this <IndexEntry> element, they will navigate to the bookmark named "#bookmark", where bookmark is the value of the attribute.
See <DocBrowserStaticPages> for an example of how <IndexEntry> is used.
(Optional, used within <WriteDocumentation>, multiple allowed.) Specifies C# attribute declarations (in [square brackets]) that are omitted from the documentation.
| XML |
| <HideAttributes Regex="..." /> |
Regex
(String, required.) A .NET Framework regular expression. Any attribute declaration (what's inside the square brackets) that matches this regular expression is omitted from the documentation.
The following example shows how to omit all "[DebuggerDisplay(...)]"
attributes.
| XML |
|
<WriteDocumentation>
...
<HideAttributes Regex="^DebuggerDisplay" />
...
</WriteDocumentation>
|
(Optional, used within <WriteDocumentation>, multiple allowed.) Specifies which members are included in the documentation set.
Note that <IncludeNamespaces> takes precendence over <IncludeMembers>: if <IncludeNamespaces> elements result in a given namespace being excluded from the documentation set, all members of that namespace are excluded, regardless of any <IncludeMembers> elements.
| XML |
| <IncludeMembers Regex="..." /> |
Regex
(String, required.) A .NET Framework regular expression. Any member whose qualified name (including namespace) matches this regular expression is included in the documentation set. If no <IncludeMembers> elements are specified within a given <WriteDocumentation> element, then all members in C# source files specified by <ReadSource> (except those members in namespaces implicitly excluded by <IncludeNamespaces> elements) are included in the documentation set.
The following example shows how to generate documentation only for members (types, methods, properties, etc) whose qualified name include the string "Foo" or "Bar".
| XML |
|
<WriteDocumentation>
...
<IncludeMembers Regex="Foo" />
<IncludeMembers Regex="Bar" />
...
</WriteDocumentation>
|
(Optional, used within <WriteDocumentation>, multiple allowed.) Specifies which namespaces are included in the documentation set. See also: <IncludeMembers>.
| XML |
| <IncludeNamespaces Regex="..." /> |
Regex
(String, required.) A .NET Framework regular expression. Any namespace whose qualified name matches this regular expression is included in the documentation set. If no <IncludeNamespaces> elements are specified within a given <WriteDocumentation> element, then all namespaces in C# source files specified by <ReadSource> are included in the documentation set.
The following example shows how to generate documentation only for namespaces "Abc.Def", "Abc.Ghi", and child namespace of "Abc.Ghi". (Note that ^ matches the beginning of a string, $ matches the end of a string, \. matches a period (.), and \b matches a word boundary.)
| XML |
|
<WriteDocumentation>
...
<IncludeNamespaces Regex="^Abc\.Def$" />
<IncludeNamespaces Regex="^Abc\.Ghi\b" />
...
</WriteDocumentation>
|
(Optional, used within <CodeDoc>, multiple allowed.) Reads one or more C# source files into the documentation set.
| XML |
|
<ReadSource Path="..." Prefix="..."> <Assembly>...</Assembly>
</ReadSource>
|
Path
(String, required.) The path to a source file (with a ".cs" extension) or directory, relative to the directory containing the CodeDoc XML project file. If a directory is specified, all .cs files in that directory and all subdirectories are included, except for those excluded by nested <ExcludeFilePaths> elements.
Prefix
(String, optional.) If specified, this string is used as a prefix for table of contents entries generated by a subsequent <SourceFilesNode> element. For example, if Prefix="Abc", and Path refers to a directory named "Def", and that directory contains a file named "Ghi.cs", then the table of contents entry for "Ghi.cs" that's generated by <WriteFormattedCode> is "Abc\Ghi.cs". Note that, in this example, "Def" does not appear in the path. If you want it to, specify it explicitly: Prefix="Abc\Def". Then, the table of contents entry for "Ghi.cs" would be "Abc\Def\Ghi.cs". If Prefix is not specified, no prefix is used; in the preceding example, the table of contents entry for "Ghi.cs" would appear as "Ghi.cs". (If "Ghi.cs" were in a subdirectory of "Def", the subdirectory name would appear in the table of contents entries in all cases described above.)
See <WriteDocumentation> and <WriteFormattedCode> for examples of how <ReadSource> is used.
(Optional, used within <WriteFormattedCode>.) Specifies a source file renderer to use in place of the default source file renderer. A source file renderer is a .NET class that is responsible for generating formatted source code HTML files from parsed C# files. The <SourceFileRenderer> feature allows you to write your own source file renderer to use in place of the default one.
The DLL containing the source file renderer must be placed in the same directory as CodeDoc.exe, or in the global assembly cache.
The default source file renderer is the class DwellNet.CodeDoc.DefaultSourceFileRenderer within CodeDocRenderer.dll.
This is an advanced feature, provided only for cases where a high level of extensibility is required.
| XML |
|
<SourceFileRenderer Assembly="..." Type="..." /> |
Assembly
(String, required.) The name of the assembly containing the source file renderer, without the ".dll" extension.
Type
(String, required.) The fully-qualified name of the source file renderer class. This class must derive from DwellNet.CodeDoc.SourceFileRenderer.Class (defined in CodeDocApi.dll).
| XML |
|
<SourceFileRenderer
Assembly="MyCodeDocRenderer"
Type="MyNamespace.MySourceFileRenderer" />
|
(Optional, used within <WriteFormattedCode>.) Specifies that one DocBrowser table of content entry should be created corresponding to each source file that's formatted by the parent <WriteFormattedCode> element. Additionally, <SourceFilesNode> specifies the Web page that will serve as the parent page of the source file nodes: in the table of contents, expanding this parent page will reveal the source files.
<SourceFilesNode> is used exactly the same as <DocBrowserNode>, and has the same attributes and child elements. The difference is that table of contents entries for each formatted source code file are automatically added as children of the Web page specified by <SourceFilesNode>.
| XML |
|
<SourceFilesNode InitiallyExpanded="..." NewFileName="..." NodeId="..." Path="..." Title="..."> <IndexEntry>...</IndexEntry>
<DocBrowserNode>...</DocBrowserNode>
</SourceFilesNode>
|
Attributes are the same as for the <DocBrowserNode> element.
See <WriteFormattedCode> for an example of how <SourceFilesNode> is used.
(Optional, used within <WriteDocumentation> and <WriteFormattedCode>.) Specifies a topic renderer to use in place of the default topic renderer. A topic renderer is a .NET class that is responsible for generating documenation topics from XML comments within parsed C# files. The <TopicRenderer> feature allows you to write your own topic renderer to use in place of the default one.
The DLL containing the topic renderer must be placed in the same directory as CodeDoc.exe, or in the global assembly cache.
The default topic renderer is the class DwellNet.CodeDoc.DefaultTopicRenderer within CodeDocRenderer.dll.
This is an advanced feature, provided only for cases where a high level of extensibility is required.
| XML |
|
<TopicRenderer Assembly="..." Type="..." /> |
Assembly
(String, required.) The name of the assembly contining the topic renderer, without the ".dll" extension.
Type
(String, required.) The fully-qualified name of the topic renderer class. This class must derive from DwellNet.CodeDoc.TopicRenderer.Class (defined in CodeDocApi.dll).
| XML |
|
<TopicRenderer
Assembly="MyCodeDocRenderer"
Type="MyNamespace.MyTopicRenderer" />
|
(Optional, used within <CodeDoc>.) Generates one documentation topic HTML page for each C# XML comment within a specified documentation set.
The documentation set is defined by preceding <ClearSources> and <ReadSource> elements and the value of the ExternalOnly property.
| XML |
|
<WriteDocumentation ExternalOnly="..." MarkOfTheWeb="..." Path="..." TopicFooterHtml="..."> <AddToDocBrowser>...</AddToDocBrowser>
</WriteDocumentation>
|
ExternalOnly
(Boolean, optional, default "false".)
If set to "true", only externally accessible (i.e. public and
protected) members are included in the documentation set. If false,
all members are included in the documentation set.
MarkOfTheWeb
(String, optional, default "true".) If set to "true" (the default), then the "Mark of the Web" is included on generated pages. The Mark of the Web enables pages to be loaded into Internet Explorer 6.0 without a security warning when the pages are on a local hard disk. There's no good reason to use "false", but it's supported for completeness.
Path
(String, required.) The path to the directory into which generated pages are written, relative to the directory containing the CodeDoc XML project file. This is typically the DocBrowser pages directory, i.e. the directory specified by the PagesRelativePath attribute of the <CreateDocBrowser> element.
TopicFooterHtml
(String, optional.) HTML to add to the bottom of each generated page; for example, a copyright notice. If not specified, no footer HTML is added. Note that, as with all XML, characters <, >, and & must be encoded as <, >, and &, respectively. So, for example, the HTML entity reference meaning "nonbreaking space", , must be encoded as &nbsp;. Since HTML requires special encoding for <, >, and & (among others), and XML requires the same encoding, you'll sometimes need to "double-encode" these characters.
| XML |
|
<ClearSources /> <ReadSource Path="App.cs"> <Assembly Name="MyApp.exe"/>
</ReadSource> <ReadSource Path="Api" Prefix="Api"> <Assembly Name="MyApi.dll"/>
<ExcludeFilePaths Regex="\\Properties\\" />
<ExcludeFilePaths Regex="\\UnitTestData\\" />
</ReadSource> <WriteDocumentation ExternalOnly="true"
Path="Drop\Pages"
TopicFooterHtml = "Copyright (c) Your Name Here.&nbsp; All rights reserved.">
<AddToDocBrowser NodeId="TocRoot" />
</WriteDocumentation> |
(Optional, used within <CodeDoc>.) Generates one formatted source code HTML page for each C# source file within a specified documentation set. Each HTML page is a formatted version of the corresponding source file, with embedded C# XML comments converted to formatted "documentation blocks".
The documentation set is defined by preceding <ClearSources> and <ReadSource> elements.
| XML |
|
<WriteFormattedCode MarkOfTheWeb="..." Path="..." TopicFooterHtml="..."> <AddToDocBrowser>...</AddToDocBrowser>
<SourceFilesNode>...</SourceFilesNode>
</WriteFormattedCode>
|
MarkOfTheWeb
(Boolean, optional, default "true".) If set to "true" (the default), then the "Mark of the Web" is included on generated pages. The Mark of the Web enables pages to be loaded into Internet Explorer 6.0 without a security warning when the pages are on a local hard disk.
Path
(String, required.) The path to the directory into which generated pages are written, relative to the directory containing the CodeDoc XML project file. This is typically the DocBrowser pages directory, i.e. the directory specified by the PagesRelativePath attribute of the <CreateDocBrowser> element.
TopicFooterHtml
(String, optional.) HTML to add to the bottom of each generated page; for example, a copyright notice. If not specified, no footer HTML is added. Note that, as with all XML, characters <, >, and & must be encoded as <, >, and &, respectively. So, for example, the HTML entity reference meaning "nonbreaking space", , must be encoded as &nbsp;. Since HTML requires special encoding for <, >, and & (among others), and XML requires the same encoding, you'll sometimes need to "double-encode" these characters.
| XML |
|
<ClearSources /> <ReadSource Path="App.cs"> <Assembly Name="MyApp.exe"/>
</ReadSource> <ReadSource Path="Api" Prefix="Api"> <Assembly Name="MyApi.dll"/>
<ExcludeFilePaths Regex="\\Properties\\" />
<ExcludeFilePaths Regex="\\UnitTestData\\" />
</ReadSource> <WriteFormattedCode Path="Drop\Pages"
TopicFooterHtml = "Copyright (c) Your Name Here.&nbsp; All rights reserved.">
<AddToDocBrowser
IndexLabelSuffix=" (Source Code)"
NodeId="TocSource" />
<SourceFilesNode
Path="DocFiles/SourceFiles.htm"
Title="Source Code Files">
<IndexEntry>MyApp Source Code Files</IndexEntry>
<IndexEntry>Source Code Files</IndexEntry>
</SourceFilesNode>
</WriteFormattedCode> |
Except for ThermostatSample, this is the end of the documentation for users of the CodeDoc.exe console application. The remainder of the documentation, after this topic in the table of contents, is technical information about using the CodeDoc API and an overview of the CodeDoc source code.