Document! X 2022
Documentation Types / Getting Started with .NET Reference Documentation
In This Topic
    Getting Started with .NET Reference Documentation
    In This Topic

    Document! X fully supports documentation of .NET assemblies from compiled assemblies created in any .NET language, including VB.NET, C#, J#, C++/CLI and Delphi.NET. .NET Framework 1.0 - 4.7 and Silverlight are all supported.

    Document! X integrates with Microsoft® Visual Studio® (2017, 2019, and 2022) to provide you with the tools you need to author and build documentation for your Visual Studio solutions.

    .NET Reference Documentation Fundamentals

    Create a New .NET Reference Documentation Project

    Create an Empty Project

    Creating an empty project creates a project without any content. You can customize its settings according to your needs.

    To create an empty project:

    1. Click the Application Button at the upper-left of the Ribbon Menu.
    2. Click New and then select Empty Project.

       

    3. Enter a project name in the Project Name field. 
      The project is created at the default directory which is configurable in the Options Editor (Paths page). However, you can optionally choose a specific directory to save your project by browsing the Project Directory field.
             
    4. Click OK.

    The new empty project is created and opened for edit. You can now add the .NET Assemblies that you would like to document:

    1. Click Add .NET Assembly on the Project tab.

       

    2. In the .NET Assembly window, select the .NET assembly(s) to document.

    NOTE: The selected .NET assembly(s) is added to the Project Explorer under the Assemblies node.

    1. Expand down through each assembly node to select individual namespaces or types in order to update. By default private and internal types are excluded.

    A Content File is created and added to the project under the Content Files node for each .NET Assembly added to the project. You can use the Content File to author additional content in the pages that Document! X will automatically generate.

    .NET XML Comments from your source code are automatically used in the generated output. XML Comments content is displayed in the Content File Editor so you can see at a glance what content is already available from source comments and what requires further authoring.

    Author Content in Source Code XML Comments

    You can use the .NET XML comments feature to create documentation content in source code. Document! X supports all of the standard .NET XML comment tags.

    You can either author .NET XML comments manually in the source code editor or make use of the Document! X Visual Comment Editor integrated directly with Visual Studio 2017, 2019, and 2022:

    1. Open the source code file that you wish to author documentation XML comments for (C#, VB.NET and C++ supported).
    2. Click the  Edit Documentation button on the main Visual Studio toolbar.
    3. A Document! X Visual Comment Editor window opens. The tree on the left side allows you to select the code elements in the code file - select a code element and you can edit the documentation directly in the right side of the editor. Content that you author is written back to your source code as standard .NET XML comments.              
    Each time you compile your .NET assembly, the compiler extracts your source XML comments and generates an XML comment file that Document! X then uses in the documentation generation process.

    Author content outside of the source code

    If you would like to supplement the content of the pages automatically generated by Document! X and HelpStudio outside of the source code, you can do so using the Document! X and HelpStudio Content File Editor.

    The Content File Editor allows you to review and author content for any item for which a reference documentation page is generated.

    To open the Content File Editor:

    1. Expand the Content Files node on the Project Explorer.
    2. Locate the Content File for the item you wish to author content for.
    3. Right-click the Content File and select Edit.
    4. The Content File opened for edit. The tree on the left side of the editor shows you a hierarchical view of the item you are documenting.
    5. Drill down and select an item from the tree and the related documentation pages are shown in the right side of the editor.
    6. Select a specific content type from the toolbar/vertical menu to edit a specific type of content, for example, Summary, See Also, and Keywords.
    7. Type directly in the editable portions of the page on the right side of the editor.

    Add Conceptual Topics

    Conceptual information is a key part of reference documentation, providing a high level introduction, tutorials, or other conceptual information. You can easily create conceptual topics in Document! X.

    1. Click the New Topic button on the Project tab or use the Ctrl+T shortcut key.
    2. The new Topic is created in the currently-selected Topic Category on the Project Explorer (or under the (Un-categorized) node if no category is selected) and opened for edit.

       

    3. Enter your conceptual content directly in the editable area of the Topic Editor.

    You can find more information on Topic Editing in the Topic Editor topic.

    Change .NET Documentation Settings

    The settings that govern .NET documentation generation are defined in the Build Profile editor. In a new project there is a single Build Profile but you can define many build profiles if you want to create multiple outputs with different settings.

    To edit .NET documentation settings:

    1. On the Project Explorer, expand the Build Profiles node.
    2. Double-click the required Build Profile to edit the properties.
      Alternatively, you can also right-click the required Build Profile and select Edit to open the Build Profile editor.

    In the Build Profile editor, you can find the various .NET Settings pages under the Reference Documentation section.

    You can change the Template used for .NET documentation (which defines the look and feel of generated pages) on the Templates page.

           

    Identify Undocumented Items

     An essential part of delivering a complete documentation set is ensuring that all the items have been documented. Document! X includes the Undocumented Items tool to quickly and easily identify undocumented items.

    1. On the Tools tab, select the Undocumented Items option.
    2. Select the profile in the Project Profile field for which you want to find the undocumented items.
      If your project contains only one Build Profile then it appears in the Project Profile field by default.
    3. Select Item Types, for example, Class, Method, Schema, and Column, that you want to check for undocumented items.
    4. Select Content Types to indicate the items that must be considered documented (just Summary by default).
    5. Select the Content Sources that should be used when checking for content.
    6. Select Execute. Any undocumented items will be listed in the results grid.

    Build and Deploy .NET Reference Documentation

    Click the  Build button on the Project tab to build your .NET reference documentation.

    In a new project, the default Build Profile is configured to generate output in CHM HTML Help 1.x format. For .NET documentation you should change this on the Compiled Help page in the Build Profile editor to either Help 2.x (for Visual Studio 2002 - 2008) or Microsoft Help Viewer (for Visual Studio 2010, 2012, and 2013). You can also define new Build Profiles if you want to generate multiple output types.

    By default the generated documentation is integrated with Visual Studio on the local machine. Refer to the Deployment topic for more information on how to deploy your documentation to other machines.

    See Also

    Visual Studio Integration