VSdocman Help

Add to my manuals
162 Pages

advertisement

VSdocman Help | Manualzz

VSdocman Help

© 2017 Helixoft

VSdocman Help

© 2017 Helixoft

All rights reserved. No parts of this work may be reproduced in any form or by any means - graphic, electronic, or mechanical, including photocopying, recording, taping, or information storage and retrieval systems - without the written permission of the publisher.

Products that are referred to in this document may be either trademarks and/or registered trademarks of the respective owners. The publisher and the author make no claim to these trademarks.

While every precaution has been taken in the preparation of this document, the publisher and the author assume no responsibility for errors or omissions, or for damages resulting from the use of information contained in this document or from the use of programs and source code that may accompany it. In no event shall the publisher and the author be liable for any loss of profit or any other commercial damage caused or alleged to have been caused directly or indirectly by this document.

Printed: 07 2017

Contents 3

Table of Contents

Part I Introduction 7

Part II Using VSdocman 7

1 ................................................................................................................................... 7

2 ................................................................................................................................... 11

3 ................................................................................................................................... 14

4 ................................................................................................................................... 17

5 ................................................................................................................................... 19

6 ................................................................................................................................... 22

7 ................................................................................................................................... 24

8 ................................................................................................................................... 25

9 ................................................................................................................................... 25

10 ................................................................................................................................... 27

11 ................................................................................................................................... 28

Part III Project Properties 36

1 ................................................................................................................................... 40

2 ................................................................................................................................... 45

3 ................................................................................................................................... 48

Files .......................................................................................................................................................... 49

Regex Filters .......................................................................................................................................................... 50

4 ................................................................................................................................... 55

General .......................................................................................................................................................... 55

© 2017 Helixoft

3

4 VSdocman Help

Page Setup

File Nam es

.......................................................................................................................................................... 64

.......................................................................................................................................................... 65

Context Help .......................................................................................................................................................... 67

5 ................................................................................................................................... 69

Part IV VSdocman Options 71

1 ................................................................................................................................... 72

General

User Tags

.......................................................................................................................................................... 72

.......................................................................................................................................................... 74

2 ................................................................................................................................... 75

3 ................................................................................................................................... 81

Others .......................................................................................................................................................... 83

4 ................................................................................................................................... 84

Environm ent .......................................................................................................................................................... 84

Updates .......................................................................................................................................................... 85

5 ................................................................................................................................... 87

Part V Viewing and Deploying Documentation 87

1 ................................................................................................................................... 87

2 ................................................................................................................................... 88

3 ................................................................................................................................... 90

4 ................................................................................................................................... 98

5 ................................................................................................................................... 102

6 ................................................................................................................................... 104

7 ................................................................................................................................... 106

8 ................................................................................................................................... 107

Part VI Comment Tags 110

1 ................................................................................................................................... 111

2 ................................................................................................................................... 112

3 ................................................................................................................................... 112

4 ................................................................................................................................... 113

5 ................................................................................................................................... 113

6 ................................................................................................................................... 114

© 2017 Helixoft

Contents 5

7 ................................................................................................................................... 114

8 ................................................................................................................................... 115

9 ................................................................................................................................... 116

10 ................................................................................................................................... 116

11 ................................................................................................................................... 117

12 ................................................................................................................................... 118

13 ................................................................................................................................... 119

14 ................................................................................................................................... 119

15 ................................................................................................................................... 120

16 <c> ................................................................................................................................... 121

17 ................................................................................................................................... 122

18 ................................................................................................................................... 123

19 ................................................................................................................................... 123

20 <b> ................................................................................................................................... 124

21 <i> ................................................................................................................................... 124

22 <u> ................................................................................................................................... 125

23 <br> ................................................................................................................................... 125

24 ................................................................................................................................... 126

25 ................................................................................................................................... 127

26 ................................................................................................................................... 127

27 ................................................................................................................................... 128

28 ................................................................................................................................... 129

29 ................................................................................................................................... 129

30 ................................................................................................................................... 130

31 ................................................................................................................................... 130

32 ................................................................................................................................... 130

Part VII Comment Editor 131

1 ................................................................................................................................... 133

2 ................................................................................................................................... 134

3 ................................................................................................................................... 135

4 ................................................................................................................................... 136

5 ................................................................................................................................... 137

6 ................................................................................................................................... 139

7 Misc ................................................................................................................................... 140

8 ................................................................................................................................... 141

9 ................................................................................................................................... 142

Part VIII VSdocman Templates 142

1 ................................................................................................................................... 142

© 2017 Helixoft

5

6 VSdocman Help

2 ................................................................................................................................... 143

3 ................................................................................................................................... 144

Part IX Troubleshooting 154

1 ................................................................................................................................... 154

2 ................................................................................................................................... 155

3 ................................................................................................................................... 156

4 ................................................................................................................................... 156

5 ................................................................................................................................... 157

Part X About 157

Index 159

© 2017 Helixoft

Introduction 7

1 Introduction

2

VSdocman is a tool for commenting and a quick automatic generation of class documentation from your C# and VB .NET

source code files. It is ideal tool for you if you create a class library such as .NET component, control, application, smart device or w eb site (ASP .NET) projects.

VSdocman parses C# and Visual Basic .NET projects and automatically creates MSDN-like documentation w ith a table of contents, index, topics, cross-references,

IntelliSense and F1 context sensitive help

25 .

With VSdocm an you can:

·

Add, edit and consume XML comments in your source code.

·

Take advantage of its sophisticated

WYSIWYG comment editor

131

w hich helps you w rite your XML comments.

·

Easily insert tables, lists, pictures, links, class diagrams and other formatting directly in your source code.

·

Generate professional documentation in multiple and localizable output formats - HTML, CHM, Docx, MS Help View er (help for VS 2010 and higher), Help2 (help for VS 2002-2008), XML.

·

Fully integrate generated help into VS help system.

·

Generate documentation in command line mode.

·

Easily deploy MS Help View er and Help2 documentation to target computers using accompanied royalty-free command-line utility.

VSdocman w orks as an extension w ith MS Visual Studio 2017 / 2015 / 2013 / 2012. You w ill get your API reference w ith just a single mouse click. In large projects, VSdocman w ill save many days of boring tedious w ork.

See Also

How to start

7

Using VSdocman

2.1

How to Start

Here is an example of how to get documentation on your existing project in a few seconds in the easiest case.

1.

Open your VB .NET, C# or ASP .NET project in Visual Studio.

2.

The new VSdocm an item appears in Tools menu and standard toolbar as w ell.

© 2017 Helixoft

8 VSdocman Help

3.

Go to Tools - VSdocm an menu or press VSdocm an button on standard toolbar. VSdocman dialog appears. Select

Project Properties pane.

© 2017 Helixoft

Using VSdocman 9

On Code Mem bers-Mem ber Types page, check the

Com pile also non-com m ented

48 members option.

4.

On Output-Docum entation Form at page, select chm_msdn10_lightw eight documentation format.

5.

Press Com pile Project button on Compile pane. Compilation progress dialog appears and some log messages are printed in it.

© 2017 Helixoft

10 VSdocman Help

6.

You can then test generated documentation by pressing the Show Docum entation button.

See Also

Compiling the Documentation

14

© 2017 Helixoft

Using VSdocman 11

2.2

VSdocman Window

The main VSdocman dialog consists of three parts: compile buttons, project properties and program options.

Selecting a Project

When you open the w indow , the active project is the one that w as selected in the Solution Explorer or w hose code file

(document) is open and active in the IDE. You can see the name of the project in the title of Compile and Project Properties pane. When you compile, this project w ill be compiled. Any changes to project properties are made for this project.

If the solution contains more than one project, you don't need to close the VSdocman w indow , select another project and reopen the VSdocman w indow to manipulate the other project. There's a little drop-dow n arrow icon next to the project name in VSdocman w indow . Clicking it w ill allow you to directly select a new active project for editing and compilation.

© 2017 Helixoft

12 VSdocman Help

Alternatively, you can select the

solution-w ide properties

45 there too. The changes made to the previous project w ill not be lost. All changes in all projects w ill be automatically applied during compilation and they w ill be saved w hen closing this w indow .

Compile

The Com pile pane contains three buttons that allow you compiling documentation.

Com pile Project

Starts to compile documentation for the active project.

Com pile Solution to Single Docum entation

Starts to compile single documentation for current solution. That means, all VB .NET, C# and ASP .NET projects in the current solution are compiled into a single documentation w ith common settings taken from the solution-w ide properties.

Com pile Projects in Solution Separately

Starts to compile documentation for the current solution. That means, each VB .NET, C# and ASP .NET project in current solution is compiled into separate documentation w ith its ow n settings.

© 2017 Helixoft

Project Properties

Project properties let you fully customize w hat and how should be documented.

Using VSdocman 13

Each properties page is described in detail in VSdocman help. Just press F1 w hen you are on particular page or look at See

Also section at the bottom of this page.

Project profile

This selector is common to all properties pages. Here you can select for w hich project profile you w ant to edit the settings.

See

Profiles

40 for more details.

Options

Options pane contains global program options (preferences). You can define your commenting styles and some environment settings there.

There are also fields and buttons that are alw ays visible.

Active solution profile

You can select active solution profile or manage profiles here. See

Profiles

41 for more details.

OK

© 2017 Helixoft

14 VSdocman Help

Saves all settings for the current project and closes the dialog.

Cancel

Closes the dialog w ithout saving any changes in settings. If there are any changes made in the settings, the user w ill be asked w hether to save them.

Help

Show s help for VSdocman.

About

Show s the information about current version of VSdocman.

See Also

Members Compile Options

48 |

Files Compile Options

Tags Options

76 |

User Tags Options

Code Options

61

| Environment Options

74

| Output Options

84 |

Profiles

49

| Context Help Options

55 |

67 |

General Comments Options

Comment Editor Options

83 |

Page Options

72

| Built-in

64 |

Source

40

2.3

Compiling Documentation

When VSdocman is set properly, you can compile a new documentation.

Go to Tools - VSdocm an menu or press VSdocm an button on the standard toolbar.

VSdocman dialog appears.

© 2017 Helixoft

Using VSdocman 15

Check the Com pile also non-com m ented option, if you haven't used

XML comments

19 , so that all specified members be compiled, even those w ithout comments. Press the Com pile Project button on the Com pile pane. Compilation progress dialog pops up and some log messages are printed in it.

© 2017 Helixoft

16 VSdocman Help

Note, longer projects can take a little w hile to compile. You can stop compiling by the Cancel button. After compiling, press the Close button or you can test generated documentation by pressing the Show Docum entation button.

You can also compile your w hole solution at once by pressing the Com pile Solution to Single Docum entation button.

More info in

Compiling Documentation for Solution

17 .

See Also

VSdocman Options

11 |

Compiling Documentation for Solution

17 |

Adding VSdocman or XML Comment

19

© 2017 Helixoft

Using VSdocman 17

2.4

Working with Solutions

When VSdocman is set properly, you can compile a new documentation for a w hole solution.

Compiling to single documentation

Pressing Com pile Solution to Single Docum entation button in VSdocman dialog causes that every C#, VB or ASP project in the solution is compiled into a single resulting documentation. This kind of documentation is suitable if your projects share namespaces and you need one unified documentation for all of them. All members from the same namespace w ill be merged.

Some essential compilation settings such as output format (template), output path, help title, custom topics and file naming format are taken from the

solution-w ide common properties

45 . They w ill be applied to the entire documentation. Additionally, you can select other settings from the common properties that w ill override the settings from individual projects. VSdocman w ill prompt you before the compilation. You w ill probably w ant to use a single common footer text, syntax languages, etc.

The list of the selected settings w ill be remembered w hen you compile next time or from a command line.

© 2017 Helixoft

18 VSdocman Help

Compiling to multiple documentations

Pressing Com pile Projects in Solution Separately button in VSdocman dialog causes that every VB, C# or ASP project in the solution is compiled w ith its ow n settings into separate documentation. It acts exactly as thought you compiled them separately one-by-one.

In addition to project documentation, VSdocman generates one master documentation in every project's output folder. Master documentation includes links to each project documentation in the solution and its name is Solution+. It doesn't physically contain each project's documentation. It only references them depending on the output format. So you can freely make changes to sub-documents w ithout the need to change the master document. This is extremely useful in distributed team w ork. All sub documents are exactly the same as if generated for a single project.

If you plan to use the master documentation, it is necessary that all projects be set to produce documentation of the same format (HxS, CHM, HTML or other).

© 2017 Helixoft

Using VSdocman 19

So you have several projects and each of them has its master document. You only need one of them because they are all the same, others can be deleted. Click here to learn how to

view and deploy solution documentation

104

.

See Also

How to compile single project

14 |

View and Deploy Solution Documentation

104

|

Solution-w ide Properties

45

2.5

Adding Comments

·

General

19

·

Automatic Addition of Comment

19

General

VSdocman w orks fine w ithout any additional comment. All Methods, Properties, Events and other links are generated properly and parameters description tables and other fields are also included. But a user is then forced to add some additional information into these fields (describe parameters, add See Also, Exceptions links, examples and others) later. And it must be done every time w hen the new documentation is generated.

To avoid that you can include that information directly into your source code. It is done by adding special comments w hich

VSdocman (and Visual Studio) understands. VSdocman understands tw o types of comments:

1.

Standard

XML comments

22 w hich can be used in both C# and VB .NET. This is the recommended comment type and VSdocman comment editor can generate only this one.

2.

@-style comments w hich are very similar to JavaDoc comment. These comments are only recognized in VB .NET

code and VSdocman can read them only for historical reasons because they w ere used by old VBdocman for VB6 code.

Commenting is based on the tags that are included in your comments. XML tags have standard XML syntax. XML comments have prefix w hich can be defined by user, default is /// for C# and ''' for VB.

For example

Visual Basic

''' <summary>Method summary goes here.</summary>

''' <remarks>This is a remarks section.</remarks>

Sub myMethod()

C#

/// <summary>Method summary goes here.</summary>

/// <remarks>This is a remarks section.</remarks> void myMethod()

XML comments are described

here

22 in detail. If you w ish to add comments manually, the best w ay to learn them is to use

the Comment editor

131 first.

Automatic Addition of Comment

User can w rite XML comment manually but he is not required to do so. VSdocman can do that autom atically. VSdocman has an intelligent mechanism for inserting comments. Depending on code element name or type, you can easily insert predefined default comment. For example, the "Gets or sets a value indicating w hether ..." summary text is automatically generated for boolean properties. This is controlled by

comment templates

are some predefined templates for the most common cases.

75 w hich are fully customizable by user. There

When user clicks right mouse button on the code w indow , the pop-up menu appears. Menu contains Add XML Com m ent,

Com m ent Editor and Add Description Attribute items w hich perform the follow ing actions:

1.

Add XML Com m ent automatically adds the default XML comment to the current member. User can preset how the default comment should look like (see

Comment Templates

75 ). It is good for quick inserting of basic comment.

© 2017 Helixoft

20 VSdocman Help

Exam ple of autom atically added default com m ent

2.

Com m ent Editor invokes the

Comment editor

131

for selected member. This is useful w hen creating complicated documentation including hyperlinks, text formatting and others. Comment editor provides a user-friendly WYSIWYG w ay for editing the comments. If the Comment editor is invoked on member w ithout an XML comment, it is automatically filled by a default XML comment for that object.

© 2017 Helixoft

Using VSdocman 21

Exam ple of VSdocm an Com m ent Editor

3.

Add Description Attribute automatically adds the Description attribute to the current member. While documentation, F1 help and IntelliSense information is extracted from XML comments, the short property description in Properties Window must be defined w ith System.ComponentModel.Description attribute. See information about

context-help

102

.

See Also

© 2017 Helixoft

Autom atically added Description attribute

22 VSdocman Help

XML comments

22

| Comment tags

110

| Comment editor

131

|

Comment Options

76

2.6

XML comments

VSdocman provides a mechanism for developers to document their code using XML comments. In source code files, lines that begin w ith ''' in VB or /// in C# (or other user defined prefix) and that precede a user-defined type such as a class, delegate, or interface; a member such as a field, event, property, or method; or a namespace declaration can be processed as comments and placed in a file.

Example

The follow ing sample provides a basic overview of a type that has been documented.

Visual Basic

'''<summary> The main class of TestDll.</summary>

'''<remarks>Here we show how to use XML comments.</remarks>

Public Class DllClass1

'''<summary>Our sample property.</summary>

'''<remarks>This property is really interesting.</remarks>

'''<value>Some nice text.</value>

'''<example>This is an example how to use prop1 and prop2 properties.

'''<code>

''' Me.prop1 = Me.prop2

''' </code></example>

'''<author>Peter Macej</author>

'''<version>3.0</version>

'''<revision>27</revision>

'''<includesource>yes</includesource>

'''<copyright>(c) 2017 Helixoft</copyright>

'''<todo>Improve exception handling</todo>

'''<seealso cref="TestDLL.DllClass1.prop2">Another interesting

'''property</seealso>

Property prop1() As String

Get

End Get

Set(ByVal Value As String)

End Set

End Property

'''<summary>Sample method with two arguments.</summary>

'''<param name="x">The first parameter.</param>

'''<param name="y">The second parameter.</param>

'''<returns>True if no error occurs.</returns>

'''<exception cref="TestDLL.DllClass1.nestedException">If

'''something horrible happens.</exception>

Function method1(ByVal x() As Integer, ByVal y As String) As Boolean

End Function

'''<summary> This is our custom exception.</summary>

'''<remarks>This is also an example of nested class.</remarks>

<AttributeUsage(AttributeTargets.Class, AllowMultiple:=True)> _

Class nestedException

Inherits Exception

End Class

End Class

C#

///<summary> The main class of TestDll.</summary>

© 2017 Helixoft

Using VSdocman 23

///<remarks>Here we show how to use XML comments.</remarks> public class DllClass1

{

///<summary>Our sample property.</summary>

///<remarks>This property is really interesting.</remarks>

///<value>Some nice text.</value>

///<example>This is an example how to use prop1 and prop2 properties.

///<code>

/// Me.prop1 = Me.prop2

/// </code></example>

///<author>Peter Macej</author>

///<version>3.0</version>

///<revision>27</revision>

///<includesource>yes</includesource>

///<copyright>(c) 2013 Helixoft</copyright>

///<todo>Improve exception handling</todo>

///<seealso cref="TestDLL.DllClass1.prop2">Another interesting

///property</seealso>

public string prop1 {

get { }

set { }

}

///<summary>Sample method with two arguments.</summary>

///<param name="x">The first parameter.</param>

///<param name="y">The second parameter.</param>

///<returns>True if no error occurs.</returns>

///<exception cref="TestDLL.DllClass1.nestedException">If

///something horrible happens.</exception>

public bool method1(int[] x, string y)

{

}

///<summary> This is our custom exception.</summary>

///<remarks>This is also an example of nested class.</remarks>

[AttributeUsage(AttributeTargets.Class, AllowMultiple = true)]

public class nestedException : Exception

{

}

}

Code Discussion

XML documentation starts w ith ''', /// or other user defined prefix. Processing of these comments has some restrictions:

·

The documentation must be a w ell-formed XML. If the XML is not w ell-formed, VSdocman may generate an incorrect output. You can easily test your comments by launching

comment editor

131 . If everything looks fine in editor, it should look fine in the final documentation as w ell.

·

Developers are free to create their ow n set of tags. There is a built-in set of tags (see

Comment Tags

110

).

Note

Remember that XML comments must be a w ell-formed XML. Therefore some characters cannot be used in an attribute or a tag value. Those characters often appear in the source code so you have to be careful especially w hen using

<code>

120 or

<c>

121 tags. You must escape the follow ing characters:

Character quote (")

Escape sequence

&quot;

© 2017 Helixoft

24 VSdocman Help apostrophe (') ampersand (&) less than (<) greater than (>)

&apos;

&amp;

&lt;

&gt;

The safest w ay to enter these characters is to use VSdocman

WYSIWYG comment editor

131

.

See Also

Adding Comment

19

| Comment Tags

110

|

Comment Editor

131

2.7

Using Custom Topics

Default structure of generated documentation is quite simple and it only contains automatically generated API reference. A table of contents (TOC) looks like:

Help Title

Namespace1 API

Namespace2 API

...

NamespaceN API

But VSdocman allow s you to define your ow n custom topics and TOC structure. Using WYSIWYG editor, you can

create any number of custom topics

58 such as overview , examples and demos, license agreement, usage descriptions, company description, etc. You can define your ow n structure of table of contents (TOC) w ith topics and chapters. You can place generated API documentation anyw here in the TOC. You can even split API reference and insert specified namespaces at various places. This makes VSdocman really pow erful tool for creating complete end-user documentation for your class libraries and applications.

This is an example of custom documentation layout:

Overview

TestDLL Usage

Basic Functionality

Advanced

TestDLL Class Reference

Namespace2 API

...

NamespaceN API

License Agreement

About

Appendix: Demo Reference

Namespace1 API

As you can see, this is a complete end-user documentation for your class library. You can use all XML tags that you use in your XML comments. Links to and from your custom topics are fully supported too.

You can define your custom topics on

Output - Custom Topics page

58 .

See Also

Custom Topics Properties

58

© 2017 Helixoft

Using VSdocman 25

2.8

Creating and Using Context Sensitive Help

VSdocman can automatically assign all members to their help topics. This feature is extremely useful in team w ork in conjunction w ith source control and absolutely necessary for class libraries or controls developers. When distributing controls, all public methods and properties have to be documented very w ell for the end user. With VSdocman it is a matter of a couple of seconds.

Creating context sensitive docum entation

There are three types of context-sensitive help:

1.

A help topic is show n w hen you point to some member in source code or Object Brow ser and press F1.

2.

Quick summary is show n in IntelliSense and Object Brow ser.

3.

Short property description is show n in Properties Window .

All you have to do is to select the output format that supports context sensitive help. Topics in generated documentation w ill be automatically assigned to their members in the source code.

Getting context help

102

on the member is then very simple.

See Also

View and Deploy Context Help

102

|

Context Help Options

67

2.9

Using VSdocman from Command line

VSdocman can be called from a command line. How ever, you alw ays need to configure your project settings in the IDE.

Before trying VSdocman from the command line, test it from the IDE first.

To compile documentation from the command line, you need to call VSdocm anCm dLine.exe utility located in VSdocman installation folder.

Syntax

VSdocmanCmdLine.exe [/?] [/vs 2012 | 2013 | 2015]

[/devenvPath "DEVENV_EXE_PATH"]

[/operation compileProject | compileSolution | compileSolutionToSingle]

[/profile "PROFILE_NAME"]

"PROJECT_OR_SOLUTION"

Com m and Line Param eters

Param eter

PROJECT_OR_SOLUTION

/vs

/devenvPath

/operation

Description

A full absolute path to the project file (.csproj, .vbproj, ...) if the operation is compileProject. Otherw ise it is a full path to the solution file (.sln).

Version of Visual Studio w hich w as used for editing specified project or solution. This version of VS must be installed. If this parameter is omitted, the latest installed version of VS w ill be used. This parameter is only valid for VS 2012, 2013 and 2015.

For VS 2017 and new er, use the /devenvPath parameter.

The full path to the devenv.exe to be used internally. If this argument is specified, the /vs is ignored. This parameter must be used w ith VS 2017 and higher,because there may be multiple instances of the same VS version installed. Note that w hen VS 2017 w as installed after any other possible VS version on the computer, and the /vs parameter is omitted, VS

2017 w ill not be used automatically. You need to specify the /devenvPath parameter.

Operation to perform. There are three choices:

· compileProject - compiles a single project

© 2017 Helixoft

26 VSdocman Help

/profile

/retryOnCpuBusy

· compileSolution - compiles each project in a solution into separate documentation.

· compileSolutionToSingle - compiles entire solution into a single documentation. The settings from the

solution-w ide common properties

45 , that w ere selected in the IDE the last time the "

Compile Solution to Single Documentation

17 " w as executed, w ill be applied.

Profile name used. If the operation is compileProject, it must be a project profile name. Otherw ise it is a solution profile name.

The name must be enclosed in double quotes. If this parameter is omitted, the "default" profile w ill be used.

Specifies if the utility should retry w hen the operation fails due to a high CPU load. In very rare cases, it may happen that the utility exits w ith the error code 1 (Visual Studio w as not found) w ith the additional exception info: COMException

(0x80080005). This is usually caused by the current high CPU load. On the next execution everything w orks. This parameter specifies how many times and w ith w hat intervals in seconds should the utility retry automatically in such cases. The values are separated by a semicolon. If you encounter this problem, set the parameter to something like this:

/retryOnCpuBusy 3;60

Show help.

/?

Exit Codes

Code

0

1

2

3

Description

OK

Visual Studio (version specified by /vs parameter) w as not found.

Incorrect command line parameters.

Other error.

Examples

To compile documentation for an entire solution to several documents, one for each project, in the latest VS version installed:

VSdocmanCmdLine.exe /operation compileSolution /profile "My profile" "C:\SLN\solution.sln"

To compile documentation for an entire solution to a single resulting documentation, the "default" profile w ill be used:

VSdocmanCmdLine.exe /operation compileSolutionToSingle "C:\SLN\solution.sln"

To compile documentation for one project:

VSdocmanCmdLine.exe /operation compileProject /profile "My project profile" "C:\SLN\PRJ\project.vbproj"

This is the BAT file w hich compiles documentation for one project, saves all output and error messages in vsdocman.log file and checks the exit code:

Exam ple

@echo off

VSdocmanCmdLine.exe /operation compileProject "C:\SLN\PRJ\project.vbproj" 1>"vsdocman.log" 2>&1

If Errorlevel 3 Goto err3

If Errorlevel 2 Goto err2

© 2017 Helixoft

Using VSdocman 27

If Errorlevel 1 Goto err1

If Errorlevel 0 Goto err0

Goto end

:err0 echo 0: OK

Goto end

:err1 echo 1: Visual Studio (version specified by /vs parameter) was not found.

Goto end

:err2 echo 2: Incorrect command line parameters.

Goto end

:err3 echo 3: Other error.

Goto end

:end

2.10

Adding External Files

Sometimes you may w ant to insert your ow n external files in your documentation, e.g. images, CSS files, your ow n HTML topic files, etc. You can create a special folder w here you place all those files. You specify this folder in

VSdocman options

55 . When VSdocman generates documentation, w hole content of that folder is copied in the output folder and all files are also embedded in compiled MSHC, CHM or Help2 documentation.

You can reference your external files directly in your XML comments using for example

<see>

119

or

<img>

123

tags. Since the files including all subfolders are copied in the output folder, you can use relative paths.

Examples

Your folder for external files is c:\MyFiles. It contains one file myFile.html and subfolder subFolder w ith one file myPicture.png: c:\MyFiles

subFolder

myPicture.png

myFile.html

You can reference both files as follow s:

Visual Basic

'''<summary>Our sample property.</summary>

'''<remarks>Here is a link to <see

'''href="myFile.html">external file</see>.

'''Here we have picture <img src="subFolder/myPicture.png" />

'''</remarks>

'''<seealso href="myFile.html">Interesting file</seealso>

Function method1(ByVal x As Integer) As Boolean

C#

///<summary>Our sample property.</summary>

© 2017 Helixoft

28 VSdocman Help

///<remarks>Here is a link to <see

///href="myFile.html">external file</see>.

///Here we have picture <img src="subFolder/myPicture.png" />

///</remarks>

///<seealso href="myFile.html">Interesting file</seealso> public bool method1(int x)

External files must be distributed together w ith documentation file as w ell, except for Docx, MS Help View er (MSHC), HTML

Help (CHM) and Help 2 (HxS) formats. These formats contain all files packed in their file so you do not need to distribute them separately.

See Also

Adding Images in Documentation

31 |

<seealso> Tag

116

|

<see> Tag

119

| <img> Tag

123

2.11

Tips & Tricks

2.11.1 Documenting Attached Properties

VSdocman can document normal .NET properties easily. You just place your XML comments before property code. This w orks fine for dependency properties too and even w hen your property is both, a dependency property and an attached property. In all these cases the property is explicitly defined in the code and there is no problem placing the XML comments.

If you how ever have pure attached property, there is no place in the code you can add the XML comments. There's only attached property identifier field and getter/setter methods. All of them have their ow n XML comments used in their ow n documentation topics. VSdocman solves this problem by taking XML comments from external XML files. You need to create these files manually. The mechanism is the same as if

<include>

126

tag w as used. The external XML file needs to meet the follow ing conditions:

·

It must be placed in the same directory as the source code file w ith the identifier field.

·

Its name must be the same as name of the source code file w ith the identifier field, only the extension should be changed to XML. So if you have MyClass.cs or MyClass.vb source code file, the XML file must be placed in the same directory and must be named MyClass.xml.

·

The XML file may contain comments for multiple attached properties defined in the same source code file. Member's name

attribute must have value w hich equals to a full cref identifier of the attached property, as described in <include>

126

tag help.

Examples

Let's have the follow ing attached property named AttachedOnly.

In MyClass.vb:

Visual Basic

''' <summary>

''' Identifier field for <see cref="P:AttachedOnly" /> property.

''' </summary>

Public Shared ReadOnly AttachedOnlyProperty As DependencyProperty = _

DependencyProperty.RegisterAttached("AttachedOnly", _

GetType(String), _

GetType(MyClass), _

New FrameworkPropertyMetadata(Nothing, _

FrameworkPropertyMetadataOptions.AffectsRender Or FrameworkPropertyMetadataOptions.AffectsMeasure _

))

''' <summary>

''' Setter for <see cref="P:AttachedOnly" /> property.

''' </summary>

© 2017 Helixoft

Using VSdocman 29

Public Shared Sub SetAttachedOnly(ByVal element As UIElement, ByVal value As String)

element.SetValue(AttachedOnlyProperty, value)

End Sub

''' <summary>

''' Getter for <see cref="P:AttachedOnly" /> property.

''' </summary>

Public Shared Function GetAttachedOnly(ByVal element As UIElement) As String

Return CType(element.GetValue(AttachedOnlyProperty), String)

End Function

In MyClass.cs:

C#

/// <summary>

/// Identifier field for <see cref="P:AttachedOnly" /> property.

/// </summary> public static readonly DependencyProperty AttachedOnlyProperty =

DependencyProperty.RegisterAttached ("AttachedOnly",

typeof(string),

typeof(MyClass),

new FrameworkPropertyMetadata(null,

FrameworkPropertyMetadataOptions.AffectsRender |

FrameworkPropertyMetadataOptions.AffectsMeasure));

/// <summary>

/// Setter for <see cref="P:AttachedOnly" /> property.

/// </summary> public static void SetAttachedOnly(UIElement element, string value)

{

element.SetValue(AttachedOnlyProperty, value);

}

/// <summary>

/// Getter for <see cref="P:AttachedOnly" /> property.

/// </summary> public static string GetAttachedOnly(UIElement element)

{

return Convert.ToString(element.GetValue(AttachedOnlyProperty));

}

The MyClass.xml file contains the follow ing:

Exam ple

<?xml version="1.0" encoding="utf-8"?>

<doc>

<members>

<member name="P:MyNamespace.MyClass.AttachedOnly">

<summary>

External summary for attached property.

</summary>

<remarks>

This are external remarks for the property.

</remarks>

</member>

</members>

</doc>

© 2017 Helixoft

30 VSdocman Help

See Also

<include> tag

126

2.11.2 Formatting Documentation Directly in Comments

When VSdocman parses user comments, it copies a text from tags into resulting documentation. Usually, there is only a plain text w ithout any information for formatting and in most cases it is satisfactory. How ever, there is still a possibility to format the text. You can customize the output text in several w ays:

1.

Use XML formatting tags or Comment editor

30

2.

Edit generated documentation

30

3.

Use macros in VSdocman texts

30

1. Use XML formatting tags or Comment editor

If you are using XML comments, you can directly use built-in formatting tags

<b>

124

,

<i>

124

,

<u>

125

,

<code>

120

, <c>

121

,

<font>

123

,

<see>

119

,

<list>

122

or

<img>

123

. The easiest w ay is to use

WYSIWYG comment editor

131

w hich automatically creates correct comments.

The follow ing steps are only useful if the XML formatting tags are not enough for you.

2. Edit generated documentation

This is the easiest w ay how to format your text. After VSdocman generates the documentation, user can edit it in favorite external editor. It is good if there are only few changes, because changes must be done every time w hen the new documentation is generated. Generated documentation is located in the output directory as specified in VSdocman options.

DOCX and HTML

For Docx and HTML format this process is quite straightforw ard. Just edit desired files in your Docx or HTML editor.

CHM

CHM file is compiled from auxiliary HTML files using CHM compiler from Microsoft. So for CHM, there are HTML files generated for each topic. Find the HTML files w ith topics you w ant to modify and edit them. After that you must recompile new CHM file using hhc.exe compiler located in Tem plates directory of VSdocman installation. This program recognizes one commandline argument: name of CHM project file, w hich is generated by VSdocman. Its extension is HHP.

Exam ple

"c:\Program Files\VSdocman\Templates\hhc.exe" "d:\sample\TestDll\vsdoc\TestDll.hhp"

You can alw ays see how the documentation is built in the template file in

$vbdoc-exec-after$

150

macro. The best w ay is to uncomment the third line in this macro w hich creates execAfter_bak.bat file in your output folder w hich you can study later.

Help 2

Help 2 files are compiled from auxiliary HTML files using help 2 compiler from Microsoft. So for Help 2, there are HTML files generated for each topic. Find the HTML files w ith topics you w ant to modify and edit them. After that you must recompile new CHM file using HxCom p.exe compiler located in your VS SDK directory specified in

Environment Options

84 . Here is the syntax of HxComp.exe

(you must have VS SDK or VSHIK installed to see this help).

You can alw ays see how the documentation is built in the template file in

$vbdoc-exec-after$

150

macro. The best w ay is to uncomment the third line in this macro w hich creates execAfter_bak.bat file in your output folder w hich you can study later.

3. Use macros in VSdocman texts

The better solution for formatting the text seems to be using macros directly in comments. The source code using macros doesn't depend on output format, so you can use it w ith every template supporting given macro.

© 2017 Helixoft

Using VSdocman 31

End of line

The most common requirement for formatting the text is the ability to insert new line in the resulting document. VSdocman comes w ith predefined

$EOL$

31 macro, w hich provides inserting of new line.

Source code block

You often w ant to insert source code samples in the resulting document. Therefore, VSdocman comes w ith predefined

$CODE$ and $END-CODE$

31 macros, that are defined in all templates and provide formatting of source code.

Font form atting

There are several predefined macros for formatting the text:

·

$b$ and $bb$ that correspond to

<b>

124

and </b>

·

$u$ and $uu$ that correspond to

<u>

125

and </u>

·

$i$ and $ii$ that correspond to

<i>

124

and </i>

As already mentioned, all of this can and should be achieved by XML tags. So only use macros for functionality that isn't possible w ith XML tags. Define your ow n formatting macro in output templates and then use it in your comments.

See Also

Using Macros Directly in Comments

33

2.11.3 Adding New Line Directly in Comments

The most common requirement for formatting a text is the ability to insert a new line in the resulting document. Putting the text in the new line in comment doesn't help. For example, HTML ignores new line in its source text and continues to display the text on the same line. It only inserts one space before this text.

You can use

<para>

119 tag in your XML comments to start new paragraph. This is the preferred method because the

<para> tag is an official XML comment tag. Alternatively, you can use

<br>

125

tag for a line break.

See Also

<para> Tag

119

2.11.4 Adding Code Directly in Comments

You often w ant to insert source code samples in the resulting document. You can use

<code>

120

or <c>

121

tags for that in your XML comments.

2.11.5 Adding Images in Documentation

Sometimes you may w ant to insert images in your documentation, e.g. screenshots of the forms.

You can add images w ith

<img> tag

123 . The best w ay is to use

comment editor

131 .

All im age files should be located in your folder for

external files

27 . They must be distributed together w ith documentation file as w ell, except for Docx, MS Help View er (MSHC), HTML Help (CHM) and Help 2 (HxS) formats. These formats contain all images packed in their file so you do not need to distribute images separately.

See Also

<img> Tag

123

| Adding External Files in Documentation

27 |

Adding Class Diagrams in Documentation

32

© 2017 Helixoft

32 VSdocman Help

2.11.6 Adding Class Diagrams in Documentation

Class diagrams are a great w ay of show ing a structure of your code. In Visual Studio, you can create any number of class diagrams (.cd files). VSdocman allow s you to place those diagrams anyw here in your documentation, e.g. in a namespace description. A sample class diagram may look as follow s:

Code elements in generated class diagram are clickable and the links navigate to corresponding topic in HTML based output formats (HTML, CHM, MSHC, Help2).

You can add class diagrams w ith

<img> tag

123 . The best w ay is to use

comment editor

131 . Remember that you can insert only a diagram from the current project into your XML comment.

See Also

<img> Tag

123

| Adding Images in Documentation

31

2.11.7 Creating Tables With More Than Two Columns

You can insert tables using

<list>

122

tag in your comments. It is recommended to use comment editor for adding or editing tables. Normally, the <list> tag only allow s one or tw o table columns. How ever, you can extend the <list> syntax and use any number of columns. You can do it also in WYSIWYG comment editor.

Normal Tables

Normally, the table can have only one column (using <term>) or tw o columns (using <term> and <description>).

Exam ple

<list type="table">

<listheader>

© 2017 Helixoft

Using VSdocman 33

<term>A</term>

<description>B</description>

</listheader>

<item>

<term>C</term>

<description>D</description>

</item>

</list>

Previous example creates a table w ith one heading row and one normal row and tw o columns:

A

C

B

D

Tables With More Columns

To add more columns, just add another <description> tags inside <listheader> or/and <item> tags.

Exam ple

<list type="table">

<listheader>

<term>A</term>

<description>B</description>

<description>C</description>

</listheader>

<item>

<term>D</term>

<description>E</description>

<description>F</description>

</item>

</list>

Previous example creates table w ith one heading row and one normal row and three columns:

A

D

B

E

C

F

Tables w ith more than tw o columns w ill w ork correctly in WYSIWYG comment editor and all output formats.

See Also

<list> Tag

122

2.11.8 Using Macros Directly in Text

Sometimes, if XML comment tags are not enough for you, you can use macros directly.

Macros

templates

142

144

are defined and used in

but they can be called directly from comments as w ell. User can define any number of macros. Macro calls are replaced by their text during compilation.

Using the macros in your comments is deactivated by default because usually you don't need it. You must

activate this option manually

35 .

The source code w hich uses macros doesn't depend on output format, so you can use it w ith every template supporting given macro. Thus, e.g. for bold text the same macro is used w hich is defined in each template using the proper specific syntax.

Examples

This is a modified

example using formatting directives

30 so that it can be used w ith every output format. First w e need to define macro for bold text in every template (it is already predefined in all templates). Let the opening macro for bold be $b$

© 2017 Helixoft

34 VSdocman Help and closing $bb$. In every HTML based template (MSHC, Help 2, HTML and CHM) define these macros as follow s:

$b$ <b>

$bb$ </b>

Now w e can use our macros anyw here:

This is $b$a bold text$bb$.

Remarks

You can call all

macros and commands provided by VSdocman

145

, not only those defined by user. But you should be very careful and do it only w hen really necessary.

See Also

Formatting Documentation Directly in Comments

30 |

Hidden Option: Allow Macros in XML Comments

35

2.11.9 Localizing the Output

Your generated documentation can be localized to any language. That means that all titles, headings and common texts are translated, e.g. "See Also", "Properties", etc. You can select the language of the output in the

output options

57 .

There is already a predefined set of languages w hich you can directly use. If your language is not supported, you can easily add it. All translated texts are placed in a small text file, one for each language. This file is named LOCALE_NAME.txt and must be placed in localizations folder under your template folder. The LOCALE_NAME is standard locale name, e.g. en-US or de-DE. You can find a list of all locales in _locales.txt file in localizations folder. VSdocman w ill automatically find this file and w ill offer the new language in the output options.

So to add a new language you need to create a copy of en-US.txt file and give it a proper name. Then you can open it in any text editor and translate the texts. The file format is very simple and is described below . Note, the file must be UTF-8 encoded!

After you save the file you can immediately use the new language.

File format

The file format is the same as template file format. It contains only comments and macro definitions. The translated text is a value of macro. Comment is any text that is outside any macro definition. It is recommended to w rite a quote at the beginning of each comment line.

Macro definition has tw o forms. Every macro name is embedded betw een tw o "$" characters e.g. $this-is-m acro-nam e$.

Macro definition starts w ith a macro name w hich must be at the beginning of a line. If the macro name does NOT start w ith

"$vbdoc-" string, its definition continues only on that line. This is the case for most texts in the language file.

The follow ing defines macro w ith "NOTE: This member is now obsolete." value.

Exam ple

$TEXT-OBSOLETE-WARNING$ NOTE: This member is now obsolete.

Macro value itself may contain a call to other macro. It is just macro name inside "$" characters. You don't translate these macro calls. They w ill be evaluated at run-time. System takes every occurrence of "$" character in any macro value as a start of macro call. There must be also terminating "$" character, otherw ise an error occurs. If you w ant to use "$" character in the text, you must escape it by "$$".

The follow ing defines macro

$MEMBERS-PAGE-TITLE$

w ith "$MEMBER-NAME$ Members" value. The value contains call to

$MEMBER-NAME$

w hich w ill be evaluated at run-time. The resulting text w ill be e.g. "MyClass Members".

Exam ple

$MEMBERS-PAGE-TITLE$ $MEMBER-NAME$ Members

If a macro name starts w ith "$vbdoc-" string (thus complete name is "$vbdoc-rest"), its definition is all the follow ing text until the first occurrence of "$end-vbdoc-rest" string w hich also must be at the beginning of a line.

© 2017 Helixoft

Using VSdocman 35

Exam ple

$vbdoc-description-help2$

Creates latest Microsoft Help 2 (*.Hx?) documentation which looks like .NET 1.x Reference.

It supports the context sensitive help, filters, index, full-text search.

Temporary HTML files are also created and can be edited later.

Then they can be compiled by HxComp.exe program.

$end-vbdoc-description-help2$

See Also

VSdocman Templates

142

| Read-only macros

145

|

Compulsory macros

150

| Commands

152

2.11.10 Hidden Option: Generate Links to 3rd Party Assemblies

VSdocman alw ays generates correct links to .NET framew ork types, e.g. System.String. But links to referenced external types that are not a part of .NET framew ork (e.g. third-party controls) are not generated by default. Only the plain text is generated.

If you w ant to generate these links, you can set this option manually in project properties. Just open

.vsdoc file

36 for the project and change the value of VBdocm an_linkForExternalNotInFram ew ork key from 0 to -1 (there is no GUI option).

If the third-party assembly has no help installed, the links w ill point to non-existing page. When you click such a link, you'll get

"Not found" error. If the third-party assembly has installed the help in MS Help2 or MS Help View er format, then clicking the link should open a correct topic.

See Also

Project properties

36

2.11.11 Hidden Option: Allow Macros in XML Comments

It is possible to

use macros from output templates directly in your XML comments

33 . This is deactivated by default because usually you don't need it. To activate this option, you can set it manually in project properties. Just open

.vsdoc file

36 for the project and change the value of VBdocm an_allow MacrosInCom m ents key from 0 to -1 (there is no GUI option).

There is one draw back w hen macros are activated. Macros have the form: $MACRO-NAME$. If you w ant to use $ character in your comments, you have to escape it w ith $$. Otherw ise, you'll get compilation error and the documentation w on't be generated correctly.

See Also

Project properties

36 |

Using Macros Directly in Text

33

2.11.12 Hidden Option: Don't Sort "See Also" Links

By default, the links in "See Also" section defined by

<seealso> comment tag

116

are sorted alphabetically. You can suppress the sorting manually in project properties. Just open

.vsdoc file

36 for the project and change the value of

VBdocm an_dontSortSeeAlsoList key from 0 to -1 (there is no GUI option).

See Also

Project properties

36 |

<seealso> comment tag

116

2.11.13 Hidden Option: Display short names of namespaces

You can list your namespaces anyw here in your TOC structure using namespace placeholders in the

custom topics

default, the namespaces listed in the generated TOC are show n w ith their full names.

58 . By

Here is an example of such TOC:

© 2017 Helixoft

36 VSdocman Help

3

Help Title

Helixoft.Documentation.VSdocman Namespace

Helixoft.Documentation.VSdocman.Core Namespace

Helixoft.Documentation.VSdocman.Compilation Namespace

Helixoft.Documentation.VSdocman.Utils Namespace

Sometimes, how ever, you may w ish to display only the short names (just the last name part and w ithout the "Namespace" w ord), especially if all your namespaces share the same long prefix. You can do it w ith the setting in the project properties, not accessible from VSdocman GUI. Just open the

.vsdoc file

36 for the project or solution in a text editor and change the value of the VBdocm an_ListNam espacesWithShortNam es key from 0 to -1.

The previous TOC w ill then look as follow s:

Help Title

VSdocman

Core

Compilation

Utils

See Also

Project properties

36 |

Custom Topics

58

Project Properties

The settings for every project are saved in a separate file located in the same directory as your project file

(.vbproj, .csproj, ...) and named project_nam e.vsdoc. The solution settings are saved in the solution_nam e.sln.vsdoc file located in the same directory as your solution file (.sln).

You can change the project properties using the dialog w indow w hich can be invoked from Tools - VSdocm an menu or by pressing VSdocman button on standard toolbar.

When VSdocman w indow appears, select the Project Properties pane. You can see and edit the properties for the active project. By default, the active project is the one that is selected in the Solution explorer.

© 2017 Helixoft

Project Properties 37

If you have more than one

profile

40 , you can select a profile to be edited in Active solution profile or Project profile combo box. After finishing all the settings press OK button to accept changes or Cancel button to keep old settings.

Selecting the active project

When you open the w indow , the active project is the one that is selected in the Solution explorer. You can see the name of that project at the top of the right panel. All your editing and compilation is performed on this active project. To select another project as active, you don't need to close the w indow and select the desired project in the Solution explorer. Just click on the project name. A list of available projects w ill be displayed and you can select one.

© 2017 Helixoft

38 VSdocman Help

In addition to normal projects, you can select also the

Solution-w ide properties

45 . These properties don't belong to a real project but to the solution. They are used as common settings that w ill be optionally applied to each project during the

Com pile Solution to Single Docum entation

17 operation.

Copying project properties

You can copy the properties from one project to other project(s) or solution-w ide properties. The selected properties from

ALL profiles of the source project w ill be copied to the corresponding profiles of the target project(s). To copy the properties from the active project, press the Copy button under the Project Properties tree at the left.

In the first step, select w hich properties in project profiles w ill be copied.

© 2017 Helixoft

Then select the destination projects.

© 2017 Helixoft

Project Properties 39

40 VSdocman Help

When you press the Copy Properties button, the selected properties w ill be copied.

See Also

Members Compile Options

Documentation Format

57

48 |

Files Compile Options

|

Source Code Options

61

Page Options

64 |

File Names Options

65

49

|

| Conditional Compilation Options

Platforms & Framew orks Options

|

Context Help Options

67

|

53

62

|

Output Options

55 |

|

Enumerations Options

63 |

Root Namespace Options

69 |

Custom Variables

70

3.1

Profiles

VSdocman allow s you to define profiles w ith various settings for projects and solutions. This w orks the same w ay as configurations in VS.

There are tw o kinds of profiles:

1.

Project profile

2.

Solution profile

Each solution and project has alw ays at least one profile named "default". This profile cannot be deleted. If you don't need more profiles, the "default" profile is all you need for storing your settings.

Project profiles

Project profile holds a set of settings for particular project. These are settings that can be specified on VSdocman project properties pages. The project properties page contains Project profile field at the top.

© 2017 Helixoft

Project Properties 41

Here you can select for w hich project profile you w ant to edit the settings. The settings for selected profile are automatically saved w hen you close the w indow .

Note, you cannot create or delete project profile w ith this field. Moreover, selecting particular project profile in this field doesn't make this profile active! Active profile means that it w ill be used during compilation. Active project profile is determined by the solution profile selected in Active solution profile field at the bottom of the w indow and it is marked as

Active follow ed by project profile name in parentheses.

Solution profiles

Solution profile holds information about entire solution settings. You can define w hich projects w ill be included in compilation and assign project profiles to the solution profile. Moreover, the solution profile contains

solution-w ide common properties

45 .

Only solution profile can be selected as active w hich means that assigned project profiles w ill be used during compilation.

You can select active solution profile in Active solution profile field at the bottom of VSdocman w indow .

© 2017 Helixoft

42 VSdocman Help

You can invoke Profile m anager from there as w ell.

Profile manager

Profile manager allow s you to edit, create or delete project and solution profiles. You w ill find it very familiar because the interface is the same as Configuration manager of Visual Studio. To start Profile manager, open VSdocman w indow and select Profile Manager from Active solution profile field.

Active Solution Profile

© 2017 Helixoft

Project Properties 43

This option specifies active solution profile and allow s to create or delete the profile.

Creating solution profile

Select <New ...> in Active Solution Profile field.

Enter a profile name and specify from w hich solution profile the initial setting w ill be copied. If you check Also create new

project profile(s), new project profile w ith the same name as currently creating solution profile w ill be created for each project. The project profile for particular project w ill only be created if there w as no profile w ith the same name. New project profiles w ill be the clones of project profiles assigned to the solution profile specified in Copy Settings From in New

Solution Profile dialog. This w ay you'll get exact clone of existing solution profile.

Deleting solution profile

Select <Rem ove...> in Active Solution Profile field. Then you can select and remove solution profiles. The "default" profile cannot be deleted.

Managing project profiles in Profile Manager

The profile manager contains a list of all supported projects in the solution.

© 2017 Helixoft

44 VSdocman Help

Each project contains checkbox indicating w hether the project w ill be included in compilation. The Profile column specifies w hich project profile is assigned to the active solution profile. Here you can also create or delete the project profile.

Creating project profile

Click on the Profile column for the project and select <New ...> from drop-dow n menu.

Enter the profile name and specify from w hich project profile the initial setting w ill be copied. If you check Also create new

solution profile(s), a new solution profile w ith the same name as currently creating project profile w ill be created (if already not).

Deleting project profile

Click on the Profile column for the project and select <Rem ove...> from drop-dow n menu. Then you can select and remove project profiles. The "default" profile cannot be deleted.

See Also

Project Properties

36

© 2017 Helixoft

Project Properties 45

3.2

Solution-wide Properties

When you execute the

Com pile Solution to Single Docum entation

17 operation, you w ill generate a single documentation for multiple projects. The projects may have different properties and therefore w e need to specify some common properties that w ill be used in this case. There are some essential settings that must be common, such as output format (template), output path, help title, custom topics and file naming. Other settings such as footer text, regex filters may be taken w hether from individual projects or, again, from common properties. The common global properties are called

solution-w ide properties. They are part of the solution profiles stored in SOLUTION_NAME.sln.vsdoc file. Each solution profile has it's ow n solution-w ide properties.

The solution-w ide properties can be edited the same w ay as project properties. Click on the project name to show the list of available projects.

Select SOLUTION-WIDE PROPERTIES. Now you can edit the common properties. The w indow is highlighted by green color.

The Com pile button is disabled because there is no active project selected. If you w ish to compile documentation for any project, make that project active by selecting it at the top.

© 2017 Helixoft

46 VSdocman Help

So w hen you execute the Com pile Solution to Single Docum entation operation, you can select w hich common properties w ill be applied to the entire documentation and to each of its topics.

© 2017 Helixoft

Project Properties 47

The selected common properties w ill override the properties from individual projects. For example, if you select to override the page footer text, the common footer w ill be generated in all topics. Otherw ise, the topics belonging to a particular project w ill have a footer defined in that project. That means that various topics inside the same documentation w ill have different footer texts.

See Also

Project Properties

36 |

Profiles

40 |

Compiling the Documentation for Solution

17

© 2017 Helixoft

48 VSdocman Help

3.3

Code Members Options

3.3.1

Member Types

Go to Tools - VSdocm an menu or press VSdocman button on standard toolbar. VSdocman dialog appears, select Project

Properties pane. Set Code Mem bers - Mem ber Types page.

Com pile also non-com m ented m em bers

Compile also members w ithout XML or javadoc @-style comments. No comment or (if possible) inherited comment is then used.

Accessibility

Check w hich members w ith accessibility modifiers w ill be compiled. Only members w ith checked accessibility w ill be compiled. If you create a class library or a control documentation for an end user you usually need to document only public members.

Mem bers

Specify w hich members (classes, interfaces, methods, events, ...) go to the compilation. Options serve as a filter here.

© 2017 Helixoft

Project Properties 49

Option

Classes

Form s

Modules

Methods/Functions

Properties

Events

Variables

Interfaces

Structures

Meaning

Include topics for classes. If unchecked, not only topics for classes w on't be generated, neither their members such as methods or events w ill be included.

Include topics for w indow s form classes. If unchecked, not only topics for form classes w on't be generated, neither their members such as methods or events w ill be included.

Applies to VB. Include topics for modules. If unchecked, not only topics for modules w on't be generated, neither their members such as functions and variables w ill be included.

Modules are listed as NonInheritable classes w ith all members set as Shared in the final documentation.

Include topics for methods and functions.

Include topics for properties.

Include topics for events.

Include topics for class level variables (fields).

Include topics for interfaces. If unchecked, not only topics for interfaces w on't be generated, neither their members such as methods or events w ill be included.

Include topics for structures. If unchecked, not only topics for structures w on't be generated, neither their members such as methods or variables w ill be included.

Include topics for enumerations.

Include topics for extern methods (Declare in VB).

Include topics for delegates.

Include topics for class level constants.

Enum erations

Extern m ethods (Declares)

Delegates

Constants

List form s under separate category

If you view a topic for a namespace and click to the namespace members page, you see all members of that namespace grouped by type: classes, interfaces, enumerations etc. By default all classes that are forms (i.e. they inherit from Form class) are listed under classes. If you check this option, forms w ill be listed in a separate Forms category instead of Classes.

List inherited m em bers

If you view a topic for a class and click to the class members page, you see all members of that class grouped by type: constructors, methods, properties etc. If this option is unchecked you only see the members that are explicitly defined in this class. If you check this option you w ill see also all inherited members. These members are marked as inherited.

See Also

Project Properties

36

3.3.2

Files

Go to Tools - VSdocm an menu or press VSdocman button on standard toolbar. VSdocman dialog appears, select Project

Properties pane. Set Code Mem bers - Files page.

© 2017 Helixoft

50 VSdocman Help

Here is a list of all available source files in the active project. Check those w hich you w ant to compile. Unchecked file acts as if it w ould not exist in the project, so no topics for a class nor for its functions, methods, etc. w ill be created.

The files are presented as a folder tree. You can easily select and deselect w hole subtree of a folder. Each folder show s information about selected and total file count in the entire folder subtree.

See Also

Project Properties

36

3.3.3

Regex Filters

In addition to specifying member types, accessibility and files, VSdocman allow s to include or exclude documented members according to their name, declaration and attributes. You can define any number of such filters using regular expressions.

Go to Tools - VSdocm an menu or press VSdocman button on standard toolbar. VSdocman dialog appears, select Project

Properties pane. Set Code Mem bers - Regex Filters page.

© 2017 Helixoft

Project Properties 51

The page contains a list of all regex filters. There are tw o kinds of regex filters - include and exclude. A member passes the filters and it w ill be included in documentation if:

1.

at least one include filter condition is true

2.

none of the exclude filters is true

If there is no include filter, "include all" is used by default.

Editing Regex Filters

You can add or edit a regex filter using Add and Edit buttons. In both cases, the same regex editor opens.

© 2017 Helixoft

52 VSdocman Help

Filter nam e

You can define a name for the filter for better orientation. It is not necessary. If no name is defined, VSdocman uses automatically generated name based on other filter properties.

Filter type

Specifies w hether the filter is include or exclude.

Filter applies to

The regex filter matches the regex expression w ith three kinds of input:

1.

Mem ber full nam e - w hich includes namespace and class names separated by dots. Parameters if any are NOT part of this name.

2.

Mem ber com plete signature including attributes - w hich includes attributes if any, and a complete member signature w ith attributes and a return value. This input allow s for more flexibility but requires more complex regex pattern.

3.

Mem ber com plete signature w ith attributes and XML com m ents - w hich includes XML comments if any, attributes if any, and a complete member signature w ith attributes and a return value. This input allow s for more flexibility but requires more complex regex pattern.

Regular expression

Defines a regex pattern used for matching. The format is very simple. It is a standard regular expression that the input must match. You can use full regex syntax supported by .NET framew ork. In addition, if you w ant to allow any value, you don't need to use .* but you can leave the field blank. Don't forget to escape special characters like dot, comma or parentheses w ith \. If the input contains new lines, then .* stops on the next new line. To search over new lines, use (.|\n)* instead.

Test

The Test button opens the quick regex tester w here you can immediately see w hether your pattern w orks as expected.

You can even edit the pattern and apply it to the edited filter.

© 2017 Helixoft

Project Properties 53

See Also

Project Properties

36

3.3.4

Conditional Compilation

Go to Tools - VSdocm an menu or press VSdocman button on standard toolbar. VSdocman dialog appears, select Project

Properties pane. Set Code Mem bers - Conditional Com pilation page.

© 2017 Helixoft

54 VSdocman Help

You can tell VSdocman w hich members should or shouldn't appear in the resulting documentation. By default, all members that satisfy selected conditions in

Code Mem bers - Mem ber Types

48 options are included. You can set globally if you w ant to include private, public, non-commented and other members.

In addition to this, you can specify individually for each member w hether it should be included in documentation. For example, you have specified that private members should go to compilation. How ever, you have one private method w hich you don't w ant do compile. You can use the <compilew hen> tag in your comments to say w hen this member should be compiled. The value of this tag is constant and the member w ill only be compiled if that constant is listed in this dialog. This w ay you can perform conditional compilation of your documentation.

Examples

If you never w ant to include the member, use some constant that w ill never be listed in this dialog, e.g. never. Note, other members w ithout com pilew hen tag w ill alw ays be compiled, no matter w hich constants are specified in this dialog.

Visual Basic

'''<summary>Our sample property.</summary>

'''<compilewhen>never</compilewhen>

Property prop1() As String

C#

© 2017 Helixoft

Project Properties 55

///<summary>Our sample property.</summary>

/// <compilewhen>never</compilewhen> string prop1

If you w ant to include some member in your internal documentation used by your team but not in the normal documentation designed for end-user, use conditional constant e.g. internal.

Visual Basic

'''<summary>Our sample property.</summary>

'''<compilewhen>internal</compilewhen>

Property prop1() As String

C#

///<summary>Our sample property.</summary>

/// <compilewhen>internal</compilewhen> string prop1

To create the internal documentation, just enter internal in Custom conditional com pilation constants field in this dialog. To create the end-user documentation, just leave this field blank. Constant internal is not specified in this case and the member w ill not be included.

Dialog fields

Use conditional com pilation

Check this if you use conditional constants in your comments. This w ill ensure that comments are parsed during initial analysis and com pilew hen tags are processed. You can leave this option checked even w hen you don't use conditional constants but this w ill prolong compilation time.

Don't use conditional com pilation and com pile everything

If you check this option, the com pilew hen tags are ignored and compilation w ill be faster.

Custom conditional com pilation constants

Here you can specify the compilation constants. If the member contains com pilew hen tag, the member w ill be included only if a constant mentioned in that com pilew hen tag is listed here. You can specify any constant you w ish. The constant cannot contain w hitespace and it is case insensitive. To list more than one constant, use commas.

See Also

Project Properties

36 |

<compilew hen> tag

127

3.4

Output Options

3.4.1

General

Go to Tools - VSdocm an menu or press VSdocman button on standard toolbar. VSdocman dialog appears, select Project

Properties pane. Set Output - General page.

© 2017 Helixoft

56 VSdocman Help

Docum entation Title

A title of your documentation. It is used in help w indow title, TOC, topic headers, etc.

Output Folder

Specifies the output folder w here generated file(s) are to be stored. Note, w hen you generate CHM docum entation,

don't use the output path w ith w hitespaces! It's because command line compiler hhc.exe cannot compile CHM file to folder w ith w hitespaces and it returns an error.

You can use path macros such as $(ProjectDir), $(SolutionDir) and $(VSdocm anDir). For example you can define output folder as $(ProjectDir)..\..\VSdoc. This is useful w hen sharing .vsdoc project properties in a source control system.

Delete all files in output folder before com pilation

If selected, all existing files and subdirectories in the output folder w ill be deleted prior to the compilation of new documentation.

External Files Folder

Specifies folder w here your

external files

27 are located. Leave blank if you don't use any external files.

You can use path macros such as $(ProjectDir), $(SolutionDir) and $(VSdocm anDir). This is useful w hen sharing

.vsdoc project properties in source control system.

© 2017 Helixoft

Project Properties 57

See Also

Project Properties

36 |

Adding External Files

27

3.4.2

Documentation Format

Go to Tools - VSdocm an menu or press VSdocman button on standard toolbar. VSdocman dialog appears, select Project

Properties pane. Set Output - Docum entation Form at page.

Docum entation Form at

In the left frame, there is a list of all available

templates

142

. A template determines the form of output documentation. User can make his ow n templates to define new formats. VSdocman already contains these formats:

·

MS Help View er - help used in VS 2010 and higher

·

Help2 - help used in VS 2002-2008

·

CHM

·

HTML

·

docx - OOXML format used in MS Word 2007 and higher

© 2017 Helixoft

58 VSdocman Help

·

XML

Selecting a template show s its description on the right side.

Language

Specifies the language of generated documentation.There is a list of predefined languages. You can easily

add another language

34 by translating one text file. It w ill automatically appear in this list.

Tem plates Folder

You can specify a folder w here the templates are located. This is useful if you create your ow n templates. The default is

"\Templates" folder in VSdocman installation folder.

You can use path macros such as $(ProjectDir), $(SolutionDir) and $(VSdocm anDir). For example you can define the folder as $(VSdocmanDir)Templates. This is useful w hen sharing .vsdoc project properties in a source control system.

See Also

Project Properties

36

3.4.3

Custom Topics

Go to Tools - VSdocm an menu or press VSdocman button on standard toolbar. VSdocman dialog appears, select Project

Properties pane. Set Output - Custom Topics page.

© 2017 Helixoft

Project Properties 59

This is the place w here you can create your ow n additional topics and define a TOC structure. There's a topics tree on the left side and a list of properties of selected topic on the right side.

Creating, Deleting and Moving Topics

Add Root

Creates a new topic at the root level.

Add Child

Creates a new topic as a child of selected topic.

Delete button

Deletes selected topic and all of its subtopics if any.

Up and dow n buttons

Move selected topic up or dow n in the TOC. You can also move the topic w ith drag & drop.

Topic Properties

© 2017 Helixoft

60 VSdocman Help

Each topic has a set of properties. Properties of selected topic are show n on the right side. A topic is of one of the three types:

1. Topic or chapter w ith text

This topic contains an assigned text that is show n w hen you click this topic in TOC. If the topic contains sub-topics, it is called a chapter. Otherw ise it is called just a topic.

2. Chapter w ithout text

This is the chapter w hich has no text. When you click on it in the TOC, nothing is show n. It only serves as a chapter name for sub-topics.

3. Placeholder for nam espaces

This is not a real topic. It is only a placeholder for generated API for your namespaces. Each documentation should contain at least one such placeholder so that the API reference be included in it. Usually, you have one placeholder w here all your API reference is placed. But you can create unlimited number of placeholders. Placeholders are show n w ith green color and

[NAMESPACES] text in the left tree.

Topic title

This is the title show n in topic header and TOC. Title is ignored for namespaces placeholders.

Unique ID

Each topic, except for namespaces placeholders, has its ow n unique ID. Default ID is generated from the title but you can change it as you like. The ID can only contain alphanumeric and underscore characters. The ID is used in

<see>

119

and

<seealso>

116

links pointing to the topics. The cref parameter has form Y:ID. For example, you can create a link like

<see cref="Y:overview ">See overview </see>. You can use such links in other topics and also in code element comments, e.g. in class remarks. WYSIWYG comment editor supports creating and editing the links to custom topics so you don't have to remember link syntax and topic IDs.

Show as default topic

When this is checked, the topic is automatically show n w hen you open generated documentation. This is usually Overview or Introduction topic. This applies to CHM and HTML output formats. You can only have one default topic. Default topic is show n w ith blue color in the left tree.

Nam espace full nam es(s)

If the topic type is a placeholder for namespaces, you can specify w hich namespaces should appear at this place. Usually, you w ant all namespaces so you leave this field blank. Or you can use standard regular expressions to select particular namespace(s). Creating multiple placeholders w ith various filters, you can split your API reference into several parts that are placed at various places in the TOC. Remember that matching is performed w ith namespace full name. For example, if you w ant to include all namespaces starting w ith "Helixoft.Demo.", enter the follow ing:

Helixoft\.Demo\..*

There's also Test button w hich opens a regex tester so you can immediately test and modify your pattern.

Editing Topic Content

The topic content is defined the same w ay you define documentation for code elements. That means you use the same

XML comments

22 w ith tags such as <summary>, <example>, <b>, <see>, etc. Of course, you don't use XML comment prefix ''' or ///. So you can easily format your text, insert links, pictures, tables, lists, etc. There are tw o w ays of editing topic text.

Editor button

Opens

WYSIWYG editor

133

w here you can edit the topic very comfortably.

Edit source button

Opens simple text editor w here you can edit directly XML source code of the topic.

See Also

© 2017 Helixoft

Project Properties 61

Custom Topics Overview

24

3.4.4

Syntax & Source Code

Go to Tools - VSdocm an menu or press VSdocman button on standard toolbar. VSdocman dialog appears, select Project

Properties pane. Set Output - Syntax & Source Code page.

Generate syntax in the follow ing languages

Here you can select w hich languages w ill be included in generated syntax section.

Rem ove attributes from declaration syntax section in docum entation

When checked, the syntax code of the member w ill not contain any attributes, even if they are defined in source code.

Include source code in docum entation

Specifies w hether the source code w ill be included in documentation. Options:

Never - source code w ill be included for no member. The <includesource> tag is ignored.

Alw ays - source code w ill be included for every member. The <includesource> tag is ignored.

© 2017 Helixoft

62 VSdocman Help

According to <includesource> tag - source code w ill be included only for members that have its <includesource> tag set to a non empty value.

Rem ove line continuations from source code and join split lines

Only applies to Visual Basic. If checked, all lines in source code that w ere split by " _" line continuation are reformatted and joined to one line in your documentation. The original source code w ill remain unchanged.

See Also

<includesource> tag

129

|

Project Properties

36

3.4.5

Platforms & Frameworks

Go to Tools - VSdocm an menu or press VSdocman button on standard toolbar. VSdocman dialog appears, select Project

Properties pane. Set Output - Platform s & Fram ew orks page.

Platform s show n in docum entation

A text that w ill be show n in Platforms section on each member page. This is usually a comma delimited list of supported platforms.

.NET Fram ew ork

© 2017 Helixoft

Project Properties 63

A comma delimited list of supported .NET Framew ork versions. Leave empty if none. It w ill be show n on member pages in some output formats.

.NET Fram ew ork Client

A comma delimited list of supported .NET Framew ork Client versions. Leave empty if none. It w ill be show n on member pages in some output formats.

Portable Class Library

Indicates w hether Portable Class Library is supported. Leave empty if not. It w ill be show n on member pages in some output formats.

.NET for Window s Store

A comma delimited list of supported .NET for Window s Store versions. Leave empty if none. It w ill be show n on member pages in some output formats.

.NET Com pact Fram ew ork

A comma delimited list of supported .NET Compact Framew ork versions. Leave empty if none. It w ill be show n on member pages in some output formats. Moreover, if this field is not empty, the "supported by CF" icon w ill be show n besides the member name in member list.

XNA Fram ew ork

A comma delimited list of supported XNA Framew ork versions. Leave empty if none. It w ill be show n on member pages in some output formats.

Others

A list of any other framew orks. Leave empty if none. It w ill be show n on member pages in some output formats.

See Also

Project Properties

36

3.4.6

Enumerations

Go to Tools - VSdocm an menu or press VSdocman button on standard toolbar. VSdocman dialog appears, select Project

Properties pane. Set Output - Enum erations page.

© 2017 Helixoft

64 VSdocman Help

Enum eration item s sort order

Specifies in w hich order the enum items w ill be listed in generated documentation.

See Also

Project Properties

36

3.4.7

Page Setup

Go to Tools - VSdocm an menu or press VSdocman button on standard toolbar. VSdocman dialog appears, select Project

Properties pane. Set Outout - Page Setup page.

© 2017 Helixoft

Project Properties 65

Page footer text

This is a text w hich appears on the bottom of each topic page. There you can place your ow n company name, copyrights or so. You can use XML comment tags e.g. <see>, <b>, etc.

See Also

Project Properties

36

3.4.8

File Names

Go to Tools - VSdocm an menu or press VSdocman button on standard toolbar. VSdocman dialog appears, select Project

Properties pane. Set Output - File Nam es page.

© 2017 Helixoft

66 VSdocman Help

Here you can define format of names of generated HTML files.

Num eric file nam es

File name is converted to a number. It has fixed length so you w ill not exceed 260 characters limit for paths in Window s. On the other hand, it is not possible to determine w hich file belongs to w hich member so you cannot easily create links to them from external files. Moreover, numeric file name is not constant for particular member and may change each time you create new documentation.

Pretty file nam es

Pretty names are created from member's full name so you can easily create links from external files. The name is constant for particular member and it has the follow ing format:

It starts w ith frlrf. Then the full name w ithout periods and parameters if any. If method is overloaded, each variant has appended a number to the file name. This number may change so you cannot rely on it. There is still one page w ithout number w hich lists all overloads and you should point your links to that page.

If the full name is too long or your output folder name is long or very nested, you may exceed 260 characters limit for paths in

Window s. In such case you should change your output folder to something short, e,g, c:\out or you should sw itch to numeric file names.

See Also

© 2017 Helixoft

Project Properties 67

Project Properties

36 |

Adding External Files

27

3.4.9

Context Help

Go to Tools - VSdocm an menu or press VSdocman button on standard toolbar. VSdocman dialog appears, select Project

Properties pane. Set Output - Context Help page.

If this option is checked, IntelliSense and Object Brow ser quick info w ill be generated also by VSdocman (F1 help is alw ays generated).

This type of context-sensitive help w orks w ith ANY output format, including Docx, HTML, XML and others.

VSdocman generates special XML file called PROJECT_NAME.xml in your project folder (not output folder). You must place it manually in the folder w here the resulting DLL file is placed and restart Visual Studio.

Checking this option is only necessary if the sam e feature built in Visual Studio is not sufficient. For example, you w ant to exclude private members or generate the file for a w eb site. To do it directly in Visual Studio:

·

For a Visual Basic project, on the Project menu, click Properties and then Compile tab. On the Compile page, select

Generate XML documentation file.

·

For a C# project, on the Project menu, click Properties and then Build tab. On the Build page, select XML documentation file.

© 2017 Helixoft

68 VSdocman Help

How Context Help Works

If you create a project w ith reference to your DLL and you use methods or properties from that DLL, IntelliSense in Visual

Studio automatically show s their description and description of parameters as you w rite them.

Description of a method or a property is taken from their <summary> tag in comments.

Description of parameters is taken from <param> tags.

You can see the summary information in Object Brow ser as w ell.

© 2017 Helixoft

Project Properties 69

See Also

Project Properties

36 |

View and Deploy Context Help

102

3.5

Miscellanous Options

3.5.1

Root Namespace

Go to Tools - VSdocm an menu or press VSdocman button on standard toolbar. VSdocman dialog appears, select Project

Properties pane. Set Miscellanous - Root Nam espace page.

This section only applies to Visual Basic because C# doesn't have concept of a root namespace. Because root namespace has no source code representation, this dialog is the only place w here you can define a comment for the root namespace.

Root nam espace com m ent

This is an XML comment (w ithout comment prefix /// or ''') of the root namespace as it w ould appear in source code.

See Also

© 2017 Helixoft

70 VSdocman Help

Project Properties

36

3.5.2

Custom Variables

Go to Tools - VSdocm an menu or press VSdocman button on standard toolbar. VSdocman dialog appears, select Project

Properties pane. Set Miscellanous - Custom Variables page.

Custom variable 1-3

These variables are used for your ow n purposes. You can specify your paths or texts here and then access them in templates using macros $CUSTOM-VAR1$, $CUSTOM-VAR2$ and $CUSTOM-VAR3$.

See Also

Project Properties

36

© 2017 Helixoft

4

VSdocman Options 71

VSdocman Options

VSdocman requires some global settings (preferences) to w ork properly. You can change the options using the dialog w indow w hich can be invoked from Tools - VSdocm an menu or by pressing VSdocman button on standard toolbar.

VSdocman dialog appears, select Options pane.

© 2017 Helixoft

72 VSdocman Help

The options you set here w ill be applied to current Visual Studio installation. You can backup or import and export them to another computers or users w ith Im port/Export buttons. You can alw ays reset the options to factory settings. This is useful if you play w ith comment templates.

After finishing, press OK button to accept changes or Cancel button to keep old settings.

See Also

General Comments Options

Options

84

72 |

User Tags Options

74

| Comment Templates

75 |

Comment Editor Options

81 |

Environment

4.1

Comments Options

4.1.1

General

Go to Tools - VSdocm an menu or press VSdocman button on standard toolbar. VSdocman dialog appears, select Options pane. Set Com m ents - General page.

© 2017 Helixoft

VSdocman Options 73

Com m ents that VSdocm an recognizes

Select w hich comments are recognized by VSdocman.

Option

None Com m ents

XML com m ents

Old @-style com m ents

Both types of com m ents

Description

VSdocman ignores any comments.

VSdocman only recognizes standard XML comments defined by Microsoft. Most of XML comment tags are supported. See

also XML Documentation

22 .

VSdocman only recognizes old and deprecated javadoc @style comments.

VSdocman recognizes both XML and @-style comments.

C# XML com m ent line prefix

Comment prefix for C#. To distinguish XML comments from standard comment you must use some unique prefix for XML comments. It must of course start w ith //. It is recommended to use ///.

VB XML com m ent line prefix

© 2017 Helixoft

74 VSdocman Help

Comment prefix for Visual Basic. To distinguish XML comments from standard comment you must use some unique prefix for

XML comments. It must of course start w ith quote. It is recommended to use three quotes '''.

Insert VSdocm an XML com m ents instead of the VS default XML com m ents for /// or ''' key press

Indicates w hether the built-in triple typed /// or ''' are intercepted by VSdocman's Add XML Com m ent from the context menu. When enabled, VSdocman XML comments are inserted instead of the default Visual Studio XML comments w hen you type /// or '''. This allow s you to insert comments according to the comment templates, including inherited comments.

See Also

VSdocman Options

71 |

XML Documentation

22

4.1.2

User Tags

Go to Tools - VSdocm an menu or press VSdocman button on standard toolbar. VSdocman dialog appears, select Options pane. Set Com m ents - User-defined Tags page.

User Tags

You can define unlimited number of your ow n tags. If used in an XML comment, they w ill appear as a separate topic section in the same order as defined here. You can move the tags up and dow n to change this order.

XML tag nam e

A name of your XML tag.

Heading

© 2017 Helixoft

VSdocman Options 75

It is used in generated documentation as a section heading for this tag.

Text for em pty tag

A default section text that w ill be inserted in generated documentation if the tag in your XML comment is empty (has no value, e.g. <todo/>). This text w ill be generated only if the tag is empty, otherw ise it w ill be ignored and the actual tag value w ill be used. If you leave this field empty, then an empty tag in your XML comment w ill be ignored and no section (neither an empty one) w ill be generated for it. You can use this default text to create a shortcut for longer texts by simply adding an empty tag in your comment.

See Also

VSdocman Options

71 |

User Defined Tags

130

4.2

Comment Templates

VSdocman has an intelligent mechanism for inserting comments. Depending on code element name or type, you can easily insert predefined default comment. For example, the "Gets or sets a value indicating w hether ..." summary text is automatically generated for boolean properties. This is controlled by comment templates w hich are fully customizable by user.

There are some predefined templates for the most common cases.

Go to Tools - VSdocm an menu or press VSdocman button on standard toolbar. VSdocman dialog appears, select Options pane. Set Com m ent Tem plates page.

© 2017 Helixoft

76 VSdocman Help

When a user clicks right mouse button on the code w indow , the pop-up menu appears. Menu contains Add XML Com m ent item w hich automatically adds the comment to selected member. User can preset how the default comment should look like.

These options are also applied w hen creating comments w ith Comment editor.

Each code element type has its ow n template, e.g. methods, properties, etc. Moreover, you can define the templates for parameters. To edit a template, select code element type on the left and

edit its template

76 on the right.

See Also

Adding Comments

Template Macros

19

80

|

VSdocman Options

71 |

Editing Comment Template

76 |

Editing Comment Rule

78 |

Comment

4.2.1

Editing Comment Template

Comment template tells VSdocman how to generate default XML comment for a code element. It contains mechanism for intelligent generating based on element name and type.

Go to Tools - VSdocm an menu or press VSdocman button on standard toolbar. VSdocman dialog appears, select Options pane. Set element type under Com m ent Tem plates.

© 2017 Helixoft

VSdocman Options 77

Each template consists of three main parts:

1.

Flag w hether the com m ent should be inherited from an overridden or implemented member. This is only valid for methods, constructors and properties. If it is checked, VSdocman tries to inherit the comment from overridden and then from implemented members, even those from framew ork classes. If such a comment is found, it is used and no other rules are evaluated.

2.

A list of rules. Rule defines XML comment if specified condition based on element name and type is met. See

Editing comment rules

78 for more information.

© 2017 Helixoft

78 VSdocman Help

There may be any number of rules for the element. They are listed by priority. VSdocman starts evaluating the first one. If the condition is not true, the next rule is evaluated. When the rule is true, XML comment defined by that rule is used and no more rules are evaluated.

3.

Additional com m on com m ent. This is comment that w ill be appended in any case. You can use it to add your ow n or predefined XML tags w ith default text, e.g. copyright, author, etc.

To allow maximum flexibility, you can use macros in the comment definition. See the

list of macros available in comment templates

80 . For example, $DECLARING-TYPE-NAME$ macro is set to the name of declaring class/interface. You can insert macros easily using Insert Macro button.

See Also

Adding Comments

Macros

80

19 |

VSdocman Options

71 |

Comment Templates

75 |

Editing Comment Rule

78

| Comment Template

4.2.2

Editing Comment Rule

Comment rule defines XML comment for particular elements. The rule consists of conditions and XML comment. The conditions usually test element name and type. The comment from rule is applied if specified conditions are true. Rules are part of comment templates. One template may contain any number of rules. They are sorted by priority and the first rule w ith true condition is applied.

© 2017 Helixoft

VSdocman Options 79

To edit the rule, go to Tools - VSdocm an menu or press VSdocman button on standard toolbar. VSdocman dialog appears, select Options pane. Set element type under Com m ent Tem plates. Select any rule from the list and press Edit or press

Add button.

Rule nam e

Rule name has no meaning and only serves for better orientation in a list of rules.

Conditions

Depending on an element type, there are one or tw o conditions. Each element type has condition that tests its name (except constructors). Some elements also test the return or value type.

The condition format is very simple. It is a standard regular expression that the input must match. You can use full regex syntax supported by .NET framew ork. In addition, if you w ant to allow any value, you don't need to use .* but you can leave the field blank. Don't forget to escape special characters like dot, comma or parentheses w ith \.

Nam e condition

This condition tests the element's name. This is full name including namespace and class. But the name doesn't contain parameters. So if you w ant to match the "Finalize" method, you need to match anything before last dot and then "Finalize" string. So the regex is ".*\.Finalize". You w ill probably start each name condition w ith ".*\.". If the input contains new lines, then

.* stops on the next new line. To search over new lines, use (.|\n)* instead.

Type condition

This condition tests the element's type or return type. This is a full name including namespace and class. So if you w ant to match the "bool" type, your regex needs to be "System\.Boolean".

© 2017 Helixoft

80 VSdocman Help

Test buttons

The Test button opens quick regex tester w here you can immediately see w hether your pattern w orks as expected. You can even edit the pattern and apply it to edited rule.

XML Com m ent

This is XML comment that w ill be used if the rule is applied. To allow maximum flexibility, you can use macros in the comment definition. See the

list of macros available in comment templates

80 . For example, $DECLARING-TYPE-NAME$ macro is set to the name of declaring class/interface. You can insert macros easily using Insert Macro button.

See Also

Adding Comments

Macros

80

19 |

VSdocman Options

71 |

Comment Templates

75 |

Editing Comment Template

76 |

Comment Template

4.2.3

Comment Template Macros

Both, XML comment in a comment rule and common comment in a comment template w ouldn't be very useful w ithout macros.

Macro is evaluated during comment addition.

The syntax of comment macros is the same as

macro language

144 used in output templates. But you don't need to learn anything about macros. Basically, macro name is embedded betw een tw o "$" characters. You don't even need to remember comment macros because there is alw ays Insert Macro button available w hich lists all comment macros.

Com m ent m acros list

Macro

$MEMBER-NAME$

$MEMBER-FULLNAME$

$MEMBER-CREF$

$TYPE-NAME$

$TYPE-FULLNAME$

$TYPE-CREF$

$PARAMETERS$

Meaning

The short name of commented member.

The full name of commented member, including namespace and class.

The cref reference of commented member. It can be used as cref attribute of <see> tag.

The short name of value or return type of commented member.

The full name of value or return type of commented member, including namespace and class.

The cref reference of value or return type of commented member. It can be used as cref attribute of <see> tag.

The complete list of <param> tags for all parameters.

© 2017 Helixoft

VSdocman Options 81

$TYPE-PARAMETERS$

$DECLARING-TYPE-NAME$

$DECLARING-TYPE-FULLNAME$

$DECLARING-TYPE-CREF$

$DECLARING-TYPE-KIND$

$INHERITED-COMMENT-MEMBER-CREF$

$DESCRIPTION-ATTRIBUTE$

$PROPERTY-GET-OR-SET$

$DATE$

$TIME$

$COMPUTER-NAME$

$USER-NAME$

$%ENVIRONMENT-VARIABLE%$

$CURSOR$

The complete list of <typeparam> tags for all type parameters.

The short name of declaring type of commented member.

The full name of declaring type of commented member, including namespace and class.

The cref reference of declaring type of commented member. It can be used as cref attribute of <see> tag.

The type of declaring type of commented member, e.g. "class",

"interface", etc.

The cref reference of the member from w hich a comment can be inherited. It may be overridden or implemented method, property or event.

The value of System.ComponentModel.Description attribute of commented member, if any.

The standard sentence start for properties depending on presence of get and set part. For example, "Gets or sets ...".

Current date in DateTime.ToShortDateString format.

Current time in DateTime.ToShortTimeString format.

Current machine name.

Current user name.

Value of any environment variable, e.g. $%PATH%$ .

Specifies w here the cursor w ill be positioned after inserting XML comment using "Add XML comment" function. You can have several

$CURSOR$ macros in your comment. The cursor w ill be placed at the first occurrence of $CURSOR$ macro.

You can also use any

macro command

command is useful.

152

used in output templates. But in comment templates, only

$IFNOTEMPTY$

152

See Also

Adding Comments

Rule

78

19 |

VSdocman Options

71 |

Comment Templates

75 |

Editing Comment Template

76 |

Editing Comment

4.3

Comment Editor Options

4.3.1

Comment Editor Window

Go to Tools - VSdocm an menu or press VSdocman button on standard toolbar. VSdocman dialog appears, select Options pane. Set Com m ent Editor - Editor Window page.

© 2017 Helixoft

82 VSdocman Help

This dialog allow s you to set comment editor appearance.

Show com m ent editor as m odal dialog

Editor w ill open as a modal dialog.

Show com m ent editor as m odeless tool w indow

Editor w ill open as a modeless VS tool w indow . You can continue to w ork w ith IDE w hile the editor is open. You can dock or float that w indow or make it a tabbed document. It w ill behave exactly as other VS tool w indow s, e.g. Solution Explorer.

The follow ing settings apply to modeless editor.

Autom atically apply changes ...

When this option is checked, you don't need to press Apply button to apply changes from Comment editor to XML comments. When the editor looses focus or is closed, changes are automatically applied. This avoids situation w hen you have editor and source code w indow opened side by side and you forget to press Apply w hen leaving editor. On the other hand, it w ill also apply changes you made in editor but don't w ant them to apply. In such case you must undo in source code w indow .

Autom atically update content of the com m ent editor ...

© 2017 Helixoft

VSdocman Options 83

When this option is checked, the content in Comment editor w ill be automatically updated according to a currently active code element in a source code w indow . So your caret position in a code w indow is automatically reflected w ithout a need of moving focus from source code to the Comment editor.

See Also

VSdocman Options

71 |

General Editor Options

83

4.3.2

Others

Go to Tools - VSdocm an menu or press VSdocman button on standard toolbar. VSdocman dialog appears, select Options pane. Set Com m ent Editor - Others page.

This dialog allow s you to set some options of comment editor.

Word w rap in source code

If checked, the text from editor w ill be w rapped in a source code to the specified length.

© 2017 Helixoft

84 VSdocman Help

The follow ing options define how editable areas in WYSIWYG editor w ill be highlighted. For better readability, you can highlight editable regions w ith a toolbar button in the editor.

Editable region border color

A color of dotted border around editable region.

Non-editable area background color

A background color of non-editable areas. It should be a darker color not to distract user's attention from editable regions.

See Also

VSdocman Options

71 |

Comment Editor Options - Window

81

4.4

Miscellanous Options

4.4.1

Environment

Go to Tools - VSdocm an menu or press VSdocman button on standard toolbar. VSdocman dialog appears, select Options pane. Set Miscellanous - Environm ent page.

© 2017 Helixoft

VSdocman Options 85

Path to CHM com piler hhc.exe

To create a CHM file, you need the free CHM compiler utility called hhc.exe. This simple command line tool is used by

VSdocman w hen you compile documentation to CHM output format. The utility is a part of free HTML Help Workshop from

Microsoft. If you have Visual Studio installed, you probably w ill not need to install it.

Starting w ith VS 2012, the Visual Studio installer automatically installs a minimalistic version of HTML Help Workshop.

VSdocman w ill find it and you don't need to install anything. It may how ever happen, that during the compilation you'll get the follow ing error:

HHC6003: Error: The file Itircl.dll has not been registered correctly.

The best w ay to fix it is to dow nload and install the HTML Help Workshop.

This program is usually located in C:\Program Files (x86)\HTML Help Workshop folder. VSdocman tries to find the path automatically w hen started for the first time. You can also use Auto-find button anytime later. If it fails, you can do it manually. If you cannot find the file, you probably have not installed HTML Help Workshop. You can dow nload it from http://w w w .helixoft.com/vsdocman-faqs/w here-can-i-dow nload-chm-compiler-hhc-exe.html

You don't need to install HTML Help Workshop if you don't w ant to generate CHM output.

Path to HxS com piler HxCom p.exe

HxComp.exe is a compiler of Help 2 documentation (VS 2005 and 2008 help) w hich is used by Help 2 template w hen you generate Help 2 output. For VS 2005/2008 it is a part of Visual Studio 2005/2008 SDK w hich contains the Help 2 SDK. This program is usually located in C:\Program Files\Microsoft Help 2.0 SDK folder.

VSdocman tries to find that path automatically w hen started for the first time. You can also use Auto-find button anytime later. If it fails, you can do it manually. If you cannot find that file, you probably have not installed VS SDK. You can dow nload it from http://w w w .helixoft.com/vsdocman-faqs/w here-can-i-dow nload-hxcomp.exe.html

You don't need to install VS SDK if you don't w ant to generate Help 2 output.

See Also

VSdocman Options

71

4.4.2

Updates

Go to Tools - VSdocm an menu or press VSdocman button on standard toolbar. VSdocman dialog appears, select Options pane. Set Miscellanous - Updates page.

© 2017 Helixoft

86 VSdocman Help

Autom atically check for updates

If checked, VSdocman w ill connect to Helixoft w eb site in specified time intervals and it w ill check w hether a new er version is available. Note, if there is a new er version available, it w ill NOT be automatically dow nloaded and installed. You w ill be only notified and provided w ith dow nload link. Checking for updates w ill not disturb your w ork. It w ill be performed silently on the background and you w ill only be notified if new version is found. No personal information w ill be sent to us during this process. VSdocman w ill only read few bytes w ith update information from our site.

Every X days

If you select automatic update check, you can specify how often this check w ill be performed here.

Check for updates now

Checks for a new er version immediately and show s the results.

See Also

VSdocman Options

71

© 2017 Helixoft

VSdocman Options 87

4.5

Keyboard Shortcuts

You can assign your ow n keyboard shortcuts to VSdocman commands. You can do it the same w ay as for other Visual

Studio commands:

1.

Go to Visual Studio Tools - Options...

2.

Select Environm ent | Keyboard page.

3.

Assign shortcuts to the follow ing commands (enter "vsd" to Show com m ands containing field to filter out other commands):

·

VSdocm an.Com m entEditor

·

VSdocm an.AddCom m ent

·

VSdocm an.OpenVsdocm an

5 Viewing and Deploying Documentation

5.1

View and Deploy HTML Documentation

After you generate HTML documentation, you can view it by pressing Show Docum entation button on compilation dialog.

Later, you can show the documentation if you go to output folder and start index.htm l.

When deploying your documentation you need to be careful about the follow ing:

·

When deploying to w eb, letter case of all filenames is important. This is not problem on Window s but on the w eb you could encounter problems.

© 2017 Helixoft

88 VSdocman Help

See Also

View and Deploy Microsoft Help 2 Documentation

98

| View and Deploy HTML Help 1.x Documentation

88 |

View and

Deploy Solution Documentation

104

|

View and Deploy Context Help

102

5.2

View and Deploy CHM Documentation

Viewing

After you generate HTML Help 1.x (.chm) documentation, you can view it by pressing Show Docum entation button on compilation dialog.

© 2017 Helixoft

Viewing and Deploying Documentation 89

Later, you can show the documentation if you go to output folder and start PROJECT_NAME.chm .

Context help

It is not possible to integrate contents, index and search of HTML Help 1.x documentation in Visual Studio. Instead, you must use MS Help View er in VS 2017/2015/2013/2012/2010 or Microsoft Help 2 format in VS 2008/2005.

But you can provide context help from your ow n editor or application. It's possible to open any topic in CHM by a keyw ord, for example:

C#

© 2017 Helixoft

90 VSdocman Help

System.Windows.Forms.Help.ShowHelp(this, @"c:\documenattion.chm", HelpNavigator.KeywordIndex, "MyNamespace.Class1.Method1");

For this to w ork, you need to generate CHM w ith an "extended" index.

By default, VSdocman generates CHM w ith just a basic Index w hich is fully sufficient for use by humans. This means that it contains keyw ords for all code members in a short form. For example, for MyNamespace.Class1.Method1 method, there is

Method1 keyw ord in the Index. This is fine, since w hen a user w ants to find this method in the Index, he starts to type

Method1 and not its full name MyNamespace.Class1.Method1. There are tw o advantages of this basic index - index is clear and not bloated w ith too many keyw ords and mainly, no CHW file is generated (see below ). The disadvantage is that there are no keyw ords for code member full names and the code above w ill not w ork. If you don't plan to open particular topics in your CHM programmatically, w e recommend to stay w ith the basic default index.

The extended index differs from the basic index in that it contains also the full names of all code members. This has one consequence. To correctly sort and display such more complex index, the CHM runtime needs to create a special .CHW file w ith the index data. This file is automatically created the first time the Index in generated CHM file is accessed, e.g. view ed by a user. It has the same name as the CHM file and it is created in the same folder as CHM file. You need to remember this in your deployment scenarios, see below .

To create the extended index, just set the

Custom variable 3

70 to any non empty text, e.g. "use extended index". The chm_* output templates check this $CUSTOM-VAR3$ value and create the index accordingly. To create the basic index, keep the field empty.

Deploying

To deploy your CHM documentation just copy it to the destination folder. Remember that there are security restrictions

154 w hen a CHM file is placed in a netw ork location. Moreover, w hen a CHM file is dow nloaded from Internet, Window s applies security protection too. You need to right-click on the file and select Properties. Press Unblock button in the section saying that the file came from another computer. Then you can open the file by pressing ENTER.

As mentioned above, w hen you generate the extended index, a special .CHW file w ill be created at runtime. This may cause tw o potential problems.

1.

Your installer installs the CHM file to a location that requires admin w rite privileges, for example Program Files. Then a user w ithout admin rights opens the CHM and displays the Index. The help runtime w ill try to create CHW file in the protected location but it fails.

2.

Your installer installs the CHM file and the CHW file is not a part of the installation. The CHW file w ill be created later by a user. When the product is uninstalled, the CHW file w ill not be deleted and it w ill prevent the parent directories from deletion.

The solution to both problem s is to pre-create the CHW file (just open the CHM and sw itch to Index) and include it in your installer.

See Also

View and Deploy Microsoft Help 2 Documentation

98

| View and Deploy HTML Documentation

87 |

View and Deploy

Solution Documentation

104

|

View and Deploy Context Help

102

5.3

View and Deploy MS Help Viewer Documentation

Microsoft Help View er is the help format used in VS Help and MSDN for VS versions 2010 and higher.

Each Visual Studio version uses a different MS Help View er version:

Visual Studio

VS 2017

VS 2015

VS 2013

VS 2012

VS 2010

MS Help View er

MSHV 2.3

MSHV 2.2

MSHV 2.1

MSHV 2.0

MSHV 1.1

© 2017 Helixoft

Viewing and Deploying Documentation 91

MSHV versions 2.x and 1.1 are the same, they only differ in view er application and help installation process. So documentation generated w ith VSdoman w ill w ork w ith all MS Help View er versions.

After you generate MS Help View er (.msh? files) documentation, you cannot view it immediately by pressing Show

Docum entation button on compilation dialog. MS Help View er documents must be installed first. After that you can

view them in VS help

91 .

Unlike e.g. HTML Help w ith one CHM file, MS Help View er documentation usually consists of tw o files:

·

MSHC...compiled help

·

MSHA...product manifest

When VSdocman generates your MS Help View er files, it automatically registers (installs) them on your computer. See

Deploying

92 topic.

By installing your documentation in MS Help View er system w e mean:

1.

Your documentation w ill be accessible in MS Help View er system as a new book.

2.

Your help is plugged in Visual Studio help catalog so that it is visible in VS help. That means you w ill see your help in

Contents, your items w ill be in Index and you can perform search on your help.

3.

Your help is integrated in VS dynamic F1 help.

Note: By default, it is not possible to install MS Help View er documentation silently. So a Help Library Manager w indow w ill pop-up after generating the help and you must manually confirm the installation. To install help silently on target computer, you must create signed CAB file, see

Deploying

92 .

For more information, read also Getting Started w ith MS Help View er .

In this section:

·

View ing MS Help View er Docum entation

91

·

Deploying MS Help View er Docum entation

92

·

Topic Versions in MS Help View er Docum entation

97

See Also

View and Deploy HTML Help 1.x Documentation

88 |

View and Deploy HTML Documentation

87 |

View and Deploy Solution

Documentation

104

|

View and Deploy Context Help

102

5.3.1

Viewing MS Help Viewer Documentation

After you install your documentation, you can see it in VS Help. VS Help opens in a local Help View er (for VS 2010 you need to install SP1 to have the local view er). You should see your help in Contents, your items w ill be in Index and you can perform search on your help. And F1 help should w ork as w ell.

Here is a sample of MS Help View er topic show n in local Help View er 2.0:

© 2017 Helixoft

92 VSdocman Help

When you recompile your help, it needs to be installed again w hich may take several minutes. Therefore w e recommend you to compile HTML Help 1.x (chm_msdn10_lightw eight) documentation for test purposes and use MS Help View er format w hen you are satisfied w ith your documentation.

See Also

View and Deploy MS Help View er Documentation

90

| View and Deploy HTML Help 1.x Documentation

88 |

View and

Deploy HTML Documentation

87

| View and Deploy Solution Documentation

104

|

View and Deploy Context Help

102

5.3.2

Deploying MS Help Viewer Documentation

Installation

When deploying your documentation, you need to install it on a target computer. This assumes that the follow ing conditions are met:

1.

The MS Help View er runtime must be installed. It is automatically installed w hen VS 2010/2012/2013/2015 or 2017 is installed.

2.

VS 2010/2012/2013/2015 or 2017 help catalog must be installed because w e w ant to install our help into it. This requires that VS 2010/2012/2013/2015 or 2017 help w as installed during VS 2010/2012/2013/2015 or 2017 installation or separately later.

© 2017 Helixoft

Viewing and Deploying Documentation 93

As already mentioned, VSdocman generates tw o files - PROJECT_NAME.m shc and helpcontentsetup.m sha. Remember that you cannot rename helpcontentsetup.msha, otherw ise the installation w ould fail.

Installation of MSHV 1.1 and MSHV 2.x slightly differs. But VSdocman generates a single batch file w hich w ill w ork w ith any version. So you don't have to do anything special. The follow ing text explains in detail w hat's happening behind the scenes.

MS Help View er 1.x

The MS Help View er 1.x runtime contains Help Library Manager (HelpLibManager.exe) w hich is used for installing and uninstalling the help packages. It w orks in GUI mode (if invoked for example from VS Help menu) and command line mode. We w ill use the command line mode. See a full list of command line parameters for HelpLibManager .

For the installation use the follow ing syntax:

HelpLibManager.exe /product "VS" /version "100" /locale "en-us" /sourceMedia "REAL_PATH\helpcontentsetup.msha"

The first three parameters uniquely identify the help catalog w hich the installed package w ill belong to. In our case it is

VS+100+en-us catalog w hich is VS 2010 help. The /sourceMedia parameter specifies the path to our manifest file w hich contains all information necessary for installation. Unfortunately, w hen installing this w ay, the HelpLibManager.exe w ill show in GUI mode. It w ill automatically add specified help package in the list of packages but you need to manually finish the installation. The follow ing picture show s this dialog for "TestDLL Reference" help package.

You need to click the Add link next to installed package.

© 2017 Helixoft

94 VSdocman Help

Press Update button after that. An alert w ill appear.

Confirm installation w ith Yes button. The installation starts to merge indexes. This may take some time. You can exit Help

Library Manager w hen the help is installed.

© 2017 Helixoft

Viewing and Deploying Documentation 95

Uninstallation

For the uninstallation use the follow ing syntax:

HelpLibManager.exe /product "VS" /version "100" /locale "en-us" /uninstall /silent

/vendor "Helixoft" /mediaBookList "TestDLL Reference" /productName "TestDLL Reference"

Unlike the installation, the uninstallation w orks in silent mode even w hen no signed .cab files w ere used. The first three parameters uniquely identify the help catalog w hich the package w ill be uninstalled from. The /vendor , /mediaBookList and /productName w ere specified in generated helpcontentsetup.msha file during installation.

HelpLibManagerLauncher

When you install your documentation on target computer, you need to take care of the follow ing:

1.

Find path to HelpLibManager.exe. Handle situation w hen it is not found w hich means that MS Help View er runtime is not installed.

2.

Detect if HelpLibManager.exe is already running. If yes, the user must close it first.

3.

Detect installed locale of specified catalog. The /locale parameter is required for both, installation and uninstallation.

For English VS help it is en-us but w e cannot rely on it. There are various language versions of VS help or any other help catalog.

4.

When installing, the HelpLibManager.exe needs to "run as administrator". This is not necessary w hen uninstalling.

Therefore w e developed small command line tool HelpLibManagerLauncher.exe

107

that does all the job. It simply calls

HelpLibManager.exe but before this, it takes care of the abovementioned issues. Registered users of VSdocman can distribute it w ith their documentation.

MS Help View er 2.x

The process is similar to MSHV 1.x. But instead of Help Library Manager (HelpLibManager.exe) used in 1.x, version 2.x uses

Help Content Manager (HlpCtntmgr.exe) for installing and uninstalling the help packages. It is more pow erful than

HelpLibManager.exe and therefore no w rapper utility is needed to use HlpCtntmgr.exe. See a full list of command line parameters for HlpCtntmgr .

For the installation use the follow ing syntax:

HlpCtntmgr.exe /operation install /catalogName VisualStudio11|VisualStudio12 /locale en-US /sourceUri "REAL_PATH\helpcontentsetup.msha" /wait 0

The second and third parameter uniquely identify the help catalog w hich the installed package w ill belong to. In our case it is

VisualStudio11+en-US catalog w hich is a VS 2012 help. Use VisualStudio14 for VS 2014 and VisualStudio12 for VS 2013.

The /sourceUri parameter specifies the path to our manifest file w hich contains all information necessary for installation.

Unfortunately, w hen installing this w ay, the HlpCtntmgr.exe w ill show a prompt to confirm the installation.

Confirm installation w ith Yes button. The installation starts to merge indexes. This may take some time.

Uninstallation

© 2017 Helixoft

96 VSdocman Help

For the uninstallation use the follow ing syntax:

HlpCtntmgr.exe /operation uninstall /catalogName VisualStudio11|VisualStudio12 /locale en-US /vendor "Helixoft" /productName "TestDLL Reference" /bookList "TestDLL Reference" /wait 0

Unlike the installation, the uninstallation w orks in silent mode even w hen no signed .cab files w ere used. The second and third parameter uniquely identify the help catalog w hich the package w ill be uninstalled from. The /vendor , /bookList and /productName w ere specified in generated helpcontentsetup.msha file during installation.

MS Help View er 2.x and 1.x

In previous, the differences betw een MSHV 1 and 2 w ere described. Now w e are back and the follow ing applies to all MSHV versions.

Silent installation

As you can see, approach mentioned above requires user intervention. How ever, it is possible to install silently but you need to use signed CAB files. The CAB file is used instead of MSHC file.

1.

Pack your generated .mshc file into the .cab file w ith the same name and sign it. See How to generate signed .cab file from your .mshc file.

2.

Open your generated helpcontentsetup.msha file in a text editor and change .mshc to .cab in it.

3.

For installation use above-mentioned command lines but append also /silent sw itch at the end.

Im portant: When you attempt to install new er version of already installed package, the installation has no effect. So it's recommended to alw ays uninstall before installation. Uninstalling not installed package doesn't cause any problems.

Files to Deploy

As already mentioned, MS Help View er documentation consists of several files. You need to distribute all of them to other computers. VSdocman prepares deployment ready directory w ith all necessary files in output_path/FINAL_HV10_DOC folder:

·

HelpLibManagerLauncher.exe - help installation utility for MSHV 1.x.

·

register_PROJECT_NAME.bat - it determines w hich MSHV version is installed and simply calls HlpCtntmgr.exe or

HelpLibManagerLauncher.exe utility w ith proper arguments. All you need to do is to call it during installation.

·

unregister_PROJECT_NAME.bat - w hen user uninstalls your component, you should also uninstall the documentation.

Again, this script can do it for you. It it determines w hich MSHV version is installed and simply calls HlpCtntmgr.exe or

HelpLibManagerLauncher.exe utility w ith proper arguments. You should call it from your uninstaller.

·

PROJECT_NAME.m shc - MS Help View er package file. If you need silent installation, pack this file in signed CAB and edit helpcontentsetup.msha accordingly.

·

helpcontentsetup.m sha - MS Help View er manifest file.

All you need to do is to copy all those files in one folder on a target machine and call register_PROJECT_NAME.bat during installation. Or use commands from this script and call them directly.

When user uninstalls your component, you should also uninstall the documentation. Just call

unregister_PROJECT_NAME.bat from your uninstaller.

Custom izing MSHA m anifest file

The generated helpcontentsetup.msha file contains information about the book and package(s) to be registered. VSdocman fills all data automatically. There's how ever the vendor tag w ith the default "VendorName" value. You can change this value to your company's name or anything else. Just be sure not to use any underscore characters (_) there. There is a bug in MS

Help View er 2.0 and higher (VS 2012+). When there's an _ character, the registration w ill execute OK but you w ill not be able to see any contents in the help.

Distribution Policy

© 2017 Helixoft

Viewing and Deploying Documentation 97

You can distribute your documentation w ith HelpLibManagerLauncher.exe utility only if you are registered user of

VSdocman. You cannot distribute HelpLibManagerLauncher.exe if you are using evaluation (trial) or beta version of

VSdocman.

Registered users can distribute HelpLibManagerLauncher.exe royalty-free but only w ith documentation generated by

VSdocman or w ith documentation w hich contains parts generated by VSdocman.

See Also

View and Deploy MS Help View er Documentation

90

| View and Deploy HTML Help 1.x Documentation

88 |

View and

Deploy HTML Documentation

87

| View and Deploy Solution Documentation

104

|

View and Deploy Context Help

102

5.3.3

Topic Versions in MS Help Viewer Documentation

Due to the w ay, how MS Help View er handles topics, you may encounter a situation w hen your topics get in a conflict. This happens w hen you register multiple MSHC packages that contain topics w ith the same titles. For example, a custom topic named "Overview " or the same documented namespace, w hich is included in more than one MSHC. In such a case, w hen you click on such topics in TOC, no matter to w hich MSHC it belongs, only one topic is alw ays show n (usually the one that w as registered as the first). Or you can see classes from multiple packages under the namespace topic.

Topics in MS Help View er are uniquely identified by their ID. The ID must be unique among topics in the catalog that have the same locale setting. In another topics, links to this topic are constructed by using this ID. Each MSHC package generated by

VSdocman is alw ays placed under the "VS" catalog. This ensures that the package is visible in VS help view er. The problem is that VSdocman cannot guarantee that all topic IDs be unique.

Let's demonstrate the situation on the follow ing example. We have tw o VS projects for tw o components named Component1 and Component2. Each component is implemented in a single class. Each project has just one custom topic named

"Overview " and then API documentation. The generated TOC structure w ill be as follow s:

Overview ( Y:overview )

MyCom pany nam espace ( N:MyCompany )

Com ponent1 class (T:MyCompany.Component1) and

Overview ( Y:overview )

MyCom pany nam espace ( N:MyCompany )

Com ponent2 class (T:MyCompany.Component2)

VSdocman automatically generates IDs for the topics, show n above w ithin the braces. Red color indicates the IDs that are in conflict w hen both help packages are registered. As you can see, w hen a new custom topic is created, VSdocman generates a default ID from its name. In our case it is "overview " (the Y: prefix is added automatically during compilation). You can solve the problem by manually changing the ID in

custom topics properties

58 . How ever, you cannot control how IDs for code members are generated. VSdocman follow s the standards and generates IDs in cref syntax. For example, MyCompany namespace has ID "N:MyCompany". This w ay it's possible to easily create links to this topic from other help packages, similarly as VSdocman generates links to e.g. System.String topic.

Fortunately, MS Help View er uses another topic attribute - version. It is the version of the topic w hen multiple versions exist in a catalog. Because a topic Id is not guaranteed to be unique, this attribute is required w hen more than one version of a topic exists in a catalog. By default, VSdocman generates version value 10 for each topic. You can set your ow n version number for a project in

Custom variable 1

70 field in Misc properties. The $CUSTOM-VAR1$ macro is recognized and used in MS Help View er output template during compilation.

If you generate multiple help packages and there is a chance of the conflict described above, specify a different version for each project. For example, leave the field empty for Component1 project; the default 10 w ill be used. Enter 11 for the

Component2 project. That w ay you can safely register both help packages and they w ill correctly coexist in the VS help.

See Also

View and Deploy MS Help View er Documentation

90

| View and Deploy HTML Help 1.x Documentation

88 |

View and

Deploy HTML Documentation

87

| View and Deploy Solution Documentation

104

|

View and Deploy Context Help

102

© 2017 Helixoft

98 VSdocman Help

5.4

View and Deploy Help 2 Documentation

Viewing

Microsoft Help 2 is the format used in VS Help and MSDN for VS versions 2002-2008. Starting w ith VS 2010, new format named

MS Help View er

90 (alias Help 3) is used. After you generate Microsoft Help 2 (.Hx? files) documentation you cannot view it immediately by pressing Show Docum entation button on compilation dialog.

Help 2 documents must be registered first. After that you can view them in Microsoft Document Explorer - DExplore.exe (in case of VS 2005/2008). Unlike CHM documents, Help 2 documents cannot be view ed externally just by clicking them.

Window s has no view er associated w ith Help 2. But Visual Studio comes w ith its Help 2 view er - Document Explorer w hich can be used inside or outside of VS. To view documentation, you must close Document Explorer or VS after compiling documentation.

Unlike e.g. HTML Help w ith one CHM file, Help 2 documentation consists of several files:

·

HxS...compiled help

·

HxC...collection definition

· several HxK files...index files

·

HxA...attributes

·

HxT...contents

VSdocman generates and registers all Help 2 files on your computer. Your Help 2 system updates changes only if you close

Visual Studio (if the help is open inside IDE) and/or Microsoft Document Explorer. So after compilation of documentation you should close VS or Document Explorer.

By registering your documentation in Help 2 system w e mean:

1.

Your documentation w ill be accessible in Help 2 system under its ow n namespace named "vbdm.PROJECT_NAME".

2.

New filter is created for your documentation named by your project name. So your help w ill be visible under that filter.

You can see the help also under: (no filter), .NET framew ork SDK, Visual Studio, Visual Basic and Related and some other filters. If you cannot see your documentation, check w hether you use correct filter.

3.

Your help is plugged in Visual Studio help collection so that it is visible in VS help. That means you w ill see your help in

Contents, your items w ill be in Index and you can perform search on your help.

4.

Your help is integrated in VS dynamic F1 help.

Note: VSdocman tries to register your help in all VS 2002, VS 2003, VS 2005 and VS 2008. If you didn't install all of them, you w ill see error during compilation that help cannot be registered in some namespace (m s.vscc or m s.vscc.2003 or

MS.VSIPCC.v80 or MS.VSIPCC.v90). You can ignore that error.

View ing in Visual Studio

It may take several minutes to update the changes w hen you open VS help for the first time after registering your help. After that, you should see your documentation in VS help.

You should see your help in Contents, your items w ill be in Index and you can perform a search on your help. Your ow n help filter is created as w ell.

© 2017 Helixoft

Viewing and Deploying Documentation 99

To see Visual Studio dynamic help integration including context-sensitive F1 help, go to code editor and select expression w ith some method, property or other documented member. For example click on prop1 in expression If prop1 =

"hello" Then . If you press F1, the proper topic should appear.

Here is a sample of Help 2 topic:

© 2017 Helixoft

100 VSdocman Help

View ing in DExplore

Help 2 documentation cannot be view ed by specifying one file because there is no main file but a set of files as described above. Your help is registered under its ow n namespace named "vbdm.PROJECT_NAME".

DExplore uses namespace to identify w hich help to show :

DExplore.exe /helpcol ms-help://NAMESPACE_NAME

So if you type something like DExplore.exe /helpcol ms-help://vbdm.myProject, view er should open your help.

Since your help is registered in VS .NET 2002, VS .NET 2003, VS 2005 and VS 2008, you can view w hole Visual Studio collection as if you w ere in Visual Studio. Just type:

DExplore.exe /helpcol ms-help://ms.vscc

or

DExplore.exe /helpcol ms-help://ms.vscc.2003

or

© 2017 Helixoft

Viewing and Deploying Documentation 101

DExplore.exe /helpcol ms-help://ms.vscc.v80

or

DExplore.exe /helpcol ms-help://ms.vscc.v90

Im portant

When you compile and thus register your help several times, help system does not update changes even w hen you reopen

Visual Studio IDE or Document Explorer. Your help w as already registered and help system doesn't reflect that you registered it again w ith changes. The best w ay to w orkaround this is to close VS IDE or Document Explorer, unregister your help, open VS IDE or Document Explorer. You should see that your previously registered help w as removed. Close VS IDE or

Document Explorer, register new help and open VS IDE or Document Explorer again. Now you should see your new documentation.

VSdocman generates for you tw o scripts for registering and unregistering your help. They are located in output folder under names register_PROJECT_NAME.bat and unregister_PROJECT_NAME.bat. The help is already registered after compilation. So if you follow the method above, start unregister_PROJECT_NAME.bat for unregistering (previous help) and then register_PROJECT_NAME.bat for registering your (new ) help.

Tip: You can view and manage all registered Help 2 namespaces w ith free Microsoft Nam espace# 2.0

utility. Be careful if you decide to manage namespaces manually. You can irreversibly damage your help system. Please do it only if there is some problem w ith your documentation. If you decide to delete your namespace w ith this tool, make sure you first delete its plugin from m s.vscc or m s.vscc.2003 or MS.VSIPCC.v80 or MS.VSIPCC.v90 namespace.

Since help is updating every time you make some changes and it may take several minutes w e recommend you to compile

HTML Help 1.x (chm) documentation for test purposes and use Help 2 format w hen you are satisfied w ith your documentation.

Deploying

When deploying your documentation you need to register it on a target machine. There are some methods mentioned in Visual

Studio .NET Help Integration Kit (VSHIK). The method that fits our needs uses MS Installer and is quite complicated and in fact it is unusable for most developers.

Therefore w e developed small command line tool

HelixoftHelpReg.exe

106

that does all the job. Registered users of

VSdocman can distribute it w ith their documentation. VSdocman itself uses this tool for registering the help.

As already mentioned, Help 2 documentation consists of several files. You need to distribute all of them to other computers.

VSdocman prepares deployment ready directory w ith all necessary files in output_path/FINAL_DOC folder:

·

HelixoftHelpReg.exe - help registration utility. You can use

HelixoftHelpRegQ.exe

any console w indow to appear during installation.

106

instead of it if you don't w ant

·

HelpRegCfg.xm l - configuration file for HelixoftHelpReg.exe

· register_PROJECT_NAME.bat - it simply calls HelixoftHelpReg.exe utility w ith proper arguments. All you need to do is to call it during installation.

· unregister_PROJECT_NAME.bat - w hen user uninstalls your component, you should also unregister the documentation.

Again, HelixoftHelpReg.exe can do it for you. It simply calls HelixoftHelpReg.exe utility w ith proper arguments. You should call it from your uninstaller.

·

PROJECT_NAME_dyn_help.xml - VS .NET dynamic help integration file w hich should be placed in

VISUAL_STUDIO_NET\Common7\IDE\HTML\XMLLinks\LCID. LCID is language ID used on target computer. This path is usually: C:\Program Files\Microsoft Visual Studio .NET\Common7\IDE\HTML\XMLLinks\1033. This w ill be performed by

HelixoftHelpReg.exe utility.

·

8 *.Hx? files that compose Help 2 documentation.

All you need to do is to copy all those files in one folder on target machine and call register_PROJECT_NAME.bat during installation. All Hx? files must then stay in that folder. Don't delete any file, especially HelixoftHelpReg.exe because you w ill need them during uninstallation.

When user uninstalls your component, you should also unregister the documentation. Just call

unregister_PROJECT_NAME.bat from your uninstaller.

© 2017 Helixoft

102 VSdocman Help

Distribution Policy

You can distribute your documentation w ith HelixoftHelpReg.exe utility only if you are a registered user of VSdocman.

You cannot distribute HelixoftHelpReg.exe if you are using evaluation (trial) or beta version of VSdocman.

Registered users can distribute HelixoftHelpReg.exe royalty-free but only w ith documentation generated w ith VSdocman or w ith documentation w hich contains parts generated w ith VSdocman.

See Also

View and Deploy HTML Help 1.x Documentation

88 |

View and Deploy HTML Documentation

87 |

View and Deploy Solution

Documentation

104

|

View and Deploy Context Help

102

5.5

View and Deploy Context Help

Viewing

There are three types of context-sensitive help in Visual Studio:

1.

A help topic is show n w hen you point to some member in source code or Object Brow ser and press F1.

2.

Quick summary is show n in IntelliSense and Object Brow ser.

3.

Short property description is show n in Properties Window .

F1 Context help

This type is only supported by MS Help View er, Help 2 and HTML Help 1.x (CHM) formats. When you compile your help in one of these formats, context help is automatically set on your machine. You can test it w hen you restart VS IDE or Help View er after documentation compilation.

To see Visual Studio dynamic help integration including context-sensitive help, go to the code editor and select an expression w ith some method, property or other documented member. For example click on prop1 in expression If prop1 =

"hello" Then . Now if you press F1, the proper topic should appear.

You can also press F1 on some member in Object Brow ser to invoke the help topic.

IntelliSense and Object Brow ser Quick Info

This type of context-sensitive help w orks w ith ANY output format, including Docx, HTML, XML and others.

In

Context Help

67 options, you can instruct VSdocman to generate special XML file called PROJECT_NAME.xml in your project folder (not output folder). You must place it manually in the folder w here the resulting DLL file is located.

Note

Checking this option is only necessary if the sam e feature built in Visual Studio is not sufficient. For example, you w ant to exclude private members or generate the file for a w eb site. To do it directly in Visual Studio:

·

For a Visual Basic project, on the Project menu, click Properties and then Compile tab. On the Compile page, select

Generate XML documentation file.

·

For a C# project, on the Project menu, click Properties and then Build tab. On the Build page, select XML documentation file.

If you create the project w ith reference to your DLL and you use methods or properties from that DLL, IntelliSense in Visual

Studio automatically show s their description and description of parameters as you w rite them.

Description of a method or a property is taken from their <summary> tag in comments.

© 2017 Helixoft

Viewing and Deploying Documentation 103

Description of parameters is taken from <param> tags.

You can see the summary information in Object Brow ser as w ell.

Property Description in Properties Window

When you select any property of a control or a component in Properties Window , you can see a short description.

© 2017 Helixoft

104 VSdocman Help

This description is not extracted from your comments but from Description attribute of your property. So if you w ish to display this info you need to define Description attribute:

Visual Basic

<System.ComponentModel.Description("Indicates whether the toggle button is in pushed state.")> _

Public Property Pushed() As Boolean

C#

[System.ComponentModel.Description("Indicates whether the toggle button is in pushed state.")] public bool Pushed

VSdocman offers an

easy w ay to do it through a context menu

19 .

Deploying

To deploy F1 context help you must register your documentation on a target machine. RegisterHelpReg.exe utility does it automatically for Help2 and

HTML Help 1.x (CHM)

1.x)

88 . For MS Help View er, see how to

88 . See how to

deploy MS Help View er

deploy Help 2

90 .

98 and how to

deploy CHM (HTML Help

Deploying IntelliSense help is very easy. Just distribute PROJECT_NAME.xml file w ith your DLL in the same directory.

To deploy property description in Properties Window you needn't do anything. Just add Description attribute to your property and it w ill be compiled as a metadata in your assembly.

See Also

View and Deploy CHM (HTML Help 1.x) Documentation

88

| View and Deploy Help 2 Documentation

98 |

View and Deploy

MS Help View er Documentation

90 |

View and Deploy Solution Documentation

104

5.6

View and Deploy Solution Documentation

When VSdocman is set properly, you can compile a new documentation for a w hole solution.

The most likely you w ill Com pile Solution to Single Docum entation. This w ill generate single documentation w here all members are linked and namespaces are merged. In this case you don't handle this documentation in any special w ay.

If you how ever need to keep help separated for each project you need to handle multiple documents.

Pressing Com pile Projects in Solution Separately button in VSdocman dialog causes that every VB, C# or ASP project in the solution is compiled w ith its ow n settings. It acts exactly as thought you compiled them separately step-by-step.

In addition to project documentation, VSdocman generates one master documentation in every project's output folder. Master documentation includes all project documentation in the group and its name is Solution+. It doesn't physically contain all project's documentation. It only references them depending on output format. So you can freely make changes to subdocuments w ithout the need of change master document. This is extremely useful in distributed team w ork. All sub documents are exactly the same as if generated for single project.

© 2017 Helixoft

Viewing and Deploying Documentation 105

It is necessary that all projects are set to produce documentation of the same format (CHM, HTML or other).

So you have several projects and each of them has its master document. You only need one of them because they are all the same, others can be deleted.

What to do next depends on output format. Let's assume w e have solution w ith tw o projects P1 and P2.

Help 2

There are tw o possibilities how to view and deploy a set of Help 2 documents. In each case you w ill see all projects in table of contents, unified index and unified full-text search.

1.

After you compile your solution in Help 2 format, each of the project documentation is registered and after restart of

Visual Studio you can see them all. In each project's output folder there are all necessary files needed to deploy, see

Deploying Help 2 Documentation

98 . So to deploy every project's documentation just call register*.bat file for each of them during installation.

2.

Previous method has one draw back. There is one help filter and one table of contents created for each project. This is not w hat you mostly need. Usually you only w ant one filter and one contents for your component. Therefore

VSdocman creates also files to register one solution in FINAL_DOC folder. Their names all start w ith "Solution" string.

View ing

To view only one solution after you compile Help 2 documentation you must first manually unregister each project that w as automatically registered during compilation. Use unregister*Bat file generated in each project's output folder.

Then copy all Hx? files from all FINAL_DOC folders to one folder. Some of them are the same for all projects so you can overw rite them during copying. Copy also all Solution*.* ,register_solution.bat and unregister_solution.bat files to that folder. Run register_solution.bat and restart Visual Studio. Then you should see only one filter and one table of contents for w hole solution.

Deploying

Copy all Hx? files from all FINAL_DOC folders to one folder on target machine during installation. Some of them are the same for all projects so you can overw rite them during copying. Copy also all Solution*.* ,register_solution.bat and unregister_solution.bat files to that folder. Run register_solution.bat to register documentation during installation. Run unregister_solution.bat to unregister documentation during uninstallation. See

Deploying Help 2

Documentation

98 for more information.

HTML Help 1.x (CHM)

Master document contains all projects in its table of contents, unified index and unified full-text search. All you need to do is copy all project documentation to the same folder. Copy one master document from any of the projects to that folder. So you have P1.chm , P2.chm and Solution+.chm . To see master documentation open Solution+.chm .

HTML

Master document contains links to all projects. Every project documentation must be placed in folder named exactly as the project. So create the proper folders in some folder e.g. doc. Then copy all project documentation to these folders. Copy one master document from any of the projects to doc folder. So you have P1 folder w ith documentation for P1, P2 folder w ith documentation for P1 and Solution+.htm l. To see master documentation open Solution+.htm l.

XML

Master document Solution+.xm l contains a list of <project> tags w ith names of projects and corresponding XML file names.

See Also

View and Deploy Microsoft Help 2 Documentation

98

| View and Deploy HTML Help 1.x Documentation

88 |

View and

Deploy HTML Documentation

87

| View and Deploy Context Help

102

© 2017 Helixoft

106 VSdocman Help

5.7

HelixoftHelpReg.exe

VSdocman is shipped w ith small command line tools HelixoftHelpReg.exe and HelixoftHelpRegQ.exe w hich register and unregister Help 2 and HTML Help 1.x documentation on a target machine.

They are exactly the same, the only difference is that HelixoftHelpReg.exe is console application and thus command w indow is alw ays show n and HelixoftHelpRegQ.exe is quiet - it never show s any w indow . The latter is suitable for those installation programs that don't allow to control appearance of external programs called from them. For example, you can add it directly to Custom Actions in Visual Studio installer.

Both tools can be found in Redist folder in VSdocman installation folder.

Syntax

HelixoftHelpReg.exe -r|-u|-cCHM_FILE|-xCHM_FILE [-q] [-fCONFIG_FILE] [-?] [-dDYNAMIC_HELP_FILE] [-lLOG_FILE] [-z]

In addition to command line parameters, the program uses also special configuration file w hen w orking w ith Help 2.

Com m and Line Param eters

Param eter

-r

-u

-c

-x

-d

-e

-q

-f

-l

-z

-?

Configuration File

Configuration file is used w ith Help 2 to describe namespaces, titles, filters and plugins in detail. It has simple self-explanatory

XML syntax. Again, VSdocman generates this file for you so that you can deploy your documentation to the end-user.

Exam ple

<HelixoftHelpReg>

<namespace>

<name>vbdm.TestDLL</name>

Description

Register namespace and its filters, titles and plugins defined in config file. This option is used w ith Help 2.

Unregister namespace and its filters, titles and plugins defined in config file. This option is used w ith Help 2.

Register HTML Help 1.x (.CHM) file. Config file is ignored.

This option is used w ith HTML Help 1.x.

Unregister HTML Help 1.x (.CHM) file. Config file is ignored.

This option is used w ith HTML Help 1.x.

Register VS dynamic help XML file. This option is used w ith

HTML Help 1.x. The F1 integration only w orks in VS 2005 and 2008, not in new er versions.

Unregister VS dynamic help XML file. This option is used w ith HTML Help 1.x. The F1 integration only w orks in VS

2005 and 2008, not in new er versions.

Quiet mode. No messages w ill be w ritten to the standard output or log.

Path to the config file. If omitted, default HelpRegCfg.xml w ill be used. Config file is used w ith Help 2.

Path to the log file. If omitted, no logging w ill be performed.

When this argument is used, the utility alw ays returns 0

(OK) as exit code, even if there w as an error during execution. This is useful if you include HelixoftHelpReg.exe

as custom action in your MSI package and you don't w ant to cancel w hole installation if there is some problem w ith help registration. MSI automatically fails if custom action returns non-zero value.

Show help screen.

© 2017 Helixoft

Viewing and Deploying Documentation 107

<file>TestDLL_COL.HxC</file>

<description>

TestDLL Reference

</description>

</namespace>

<title>

<name>TestDLL</name>

<titleFile>TestDLL.HxS</titleFile>

<indexFile>TestDLL.HxS</indexFile>

<queryFile></queryFile>

<attrFile></attrFile>

<langId>1033</langId>

</title>

<filter>

<name>TestDLL Reference</name>

<query><![CDATA[

"DocSet"="TestDLL"

]]> </query>

</filter>

<plugin>

<parentNamespace>ms.vscc</parentNamespace>

</plugin>

<plugin>

<parentNamespace>ms.vscc.2003</parentNamespace>

</plugin>

<plugin>

<parentNamespace>MS.VSIPCC.v80</parentNamespace>

</plugin>

</HelixoftHelpReg>

Rem arks

When deploying your Help 2 documentation you need to register it on the target machine. There are some methods mentioned in Visual Studio .NET Help Integration Kit (VSHIK). The method that fits our needs uses MS Installer and is quite complicated and in fact it is unusable for most developers.

Deploying HTML Help 1.x documentation is easier but still requires some additional w ork.

That's w hy w e developed these tw o utilities that do the job for you. VSdocman itself uses this tool for registering the help.

All you need is to include and call one of them w ith proper parameters from your installation program. VSdocman automatically generates BAT files w ith correct parameters for registering and for unregistering. You can call them directly or copy the code from them.

Distribution Policy

You can distribute your documentation w ith HelixoftHelpReg.exe utility only if you are registered user of VSdocman.

You cannot distribute HelixoftHelpReg.exe if you are using evaluation (trial) or beta version of VSdocman.

Registered users can distribute HelixoftHelpReg.exe royalty-free but only w ith documentation generated by VSdocman or w ith documentation w hich contains parts generated by VSdocman.

See Also

Deploying Help2 documentation

98

| Deploying HTML Help 1.x documentation

88

5.8

HelpLibManagerLauncher.exe

VSdocman is shipped w ith small command line tool HelpLibManagerLauncher.exe w hich helps to install and uninstall MS

Help View er documentation on a target machine w ith MS Help View er 1.x installed. It simply calls Help Library Manager

(HelpLibManager.exe) but before this, it performs some preprocessing. HelpLibManager.exe is a part of MS Help View er 1.x

© 2017 Helixoft

108 VSdocman Help runtime and it is used for installing and uninstalling the help packages. See a full list of command line parameters for

HelpLibManager . HelpLibManagerLauncher.exe takes exactly the same command line parameters. So w hy not use directly

HelpLibManager.exe? Here is a list of additional tasks performed by HelpLibManagerLauncher.exe:

1.

It finds path to HelpLibManager.exe. It reports situation w hen it is not found w hich means that MS Help View er runtime is not installed.

2.

It detects if HelpLibManager.exe is already running. If yes, it reports this problem and a user must close it first.

3.

It detects installed locale of specified catalog. The /locale parameter is required for both, installation and uninstallation in HelpLibManager.exe. For English VS help it is en-us but w e cannot rely on it. There are various language versions of

VS help or any other help catalog. HelpLibManagerLauncher.exe doesn't require /locale parameter. If this parameter is omitted, program automatically finds installed locale of the catalog. This is recommended usage.

4.

When installing, the HelpLibManager.exe needs to "run as administrator". This is not necessary w hen uninstalling. The utility handles this properly.

The utility w aits until HelpLibManager.exe finishes and returns the same exit code as HelpLibManager.exe. Additionaly, it provides several new exit codes.

Syntax

HelpLibManagerLauncher.exe parameters

Com m and Line Param eters

Param eter

/product

/version

/locale

/silent

/content

/brandingPackage

/sourceMedia

/sourceWeb

Description

The product code. Ex. vs.

The product version being installed. Ex. 100.

The product locale being installed. Ex. en-us.

Perform the installation w ithout prompting the customer or displaying any UI. Digitally signed cab files are required for silent installation - .mshc files that are not deployed in signed cabs cannot be installed silently. When run in silent mode

HLM w rites a log file to the %Temp% directory.

Required if the /silent argument is present and /uninstall is not present. This specifies the location for the local content store if one has not been previously set. It is ignored if the content store location is already defined.

The file name of the branding package for the content. The branding package is an optional component that customizes the content presentation. This argument is ignored if the product already has a branding package defined.

The content installation file helpcontentsetup.msha. If the specified file is not found or is invalid, the /sourceWeb argument is used.

The URL that defines the location of content that can be dow nloaded and installed.

/mediaBookList

When not combined w ith /uninstall, this argument specifies the books to install. This argument is valid only for silent installs. If this argument is not specified, all books in the /sourceMedia file are installed. Values specified for this argument match the file names that describe each book on the media (book1.html, book2.html etc.)

When combined w ith /uninstall, this argument specifies the names of the books to be uninstalled. Use double quotes (") around books names that contain spaces and use a space

© 2017 Helixoft

Viewing and Deploying Documentation 109

/w ebBookList

/uninstall

/productName

/vendor as the delimiter for a list of books. This argument is required w hen /uninstall is specified.

Specifies the books to install. This argument is valid only for silent installs. If this argument is not specified, all books found at the /sourceWeb endpoint that match the /locale argument are installed. The book list values are fully qualified; they are not relative based on /sourceWeb.

Separate URLs using a space.

Specifies that books should be removed from the local content store. This argument requires the /silent, /productName, /mediaBookList and /vendor arguments are present.

Specifies the product name for the books that w ill be uninstalled. The product name is identified in the helpcontentsetup.msha or books.html files that shipped w ith the content. An uninstall operation can remove books only from a single product - to remove books from multiple products requires multiple uninstalls.

Specifies the vendor for the product content to be uninstalled.

Exit Codes

Original codes returned from HelpLibManager.exe:

Code

0

100

110

120

130

131

140

150

200

400

401

402

999

Additional codes returned from HelpLibManagerLauncher.exe:

Description

The operation w as successful.

One or more command line arguments w as missing or invalid.

The application configuration file for HLM w as missing or invalid.

The help content store could not be locked for update. This error typically occurs w hen the content is locked for update by another process.

Files required to install content for a new product w ere not found.

Files required to install content for a new product w ere invalid.

The path specified for the /content sw itch is invalid.

The local content store is in an invalid state. This error occurs w hen the directory permissions do not allow w riting, or a required file is missing from the directory.

The arguments passed to HLM did not result in content being installed. This can occur w hen the content is already installed.

The removal of content failed. Detailed information can be found in the event log and in the installation log.

The installation of content failed. Detailed information can be found in the event log and in the installation log.

Non-admin trying to initialize the store using /silent sw itch.

An unknow n error occurred.

© 2017 Helixoft

110 VSdocman Help

6

Code

1

2

3

4

5

6

Description

Couln't find HelpLibManager.exe.

An unknow n error occurred.

HelpLibManager.exe is already running. You need to close it in order to register the help.

Local help library store w as not initialized. You need to install some help first (e.g. VS help) in order to register your help.

Missing some command line argument.

Specified help catalog (product+version) is not installed. The new catalog couldn't be created because no /locale argument w as supplied.

Rem arks

When deploying your MS Help View er documentation you need to install it on the target computer. All you need is to include and call this utility w ith proper parameters from your installation program. VSdocman automatically generates BAT files w ith correct parameters for installing and for uninstalling. You can call them directly or copy the code from them.

Distribution Policy

You can distribute your documentation w ith HelpLibManagerLauncher.exe utility only if you are registered user of

VSdocman. You cannot distribute HelpLibManagerLauncher.exe if you are using evaluation (trial) or beta version of

VSdocman.

Registered users can distribute HelpLibManagerLauncher.exe royalty-free but only w ith documentation generated by

VSdocman or w ith documentation w hich contains parts generated by VSdocman.

See Also

Deploying MS Help View er Documentation

90

Comment Tags

VSdocman parses special XML tags w hen they are embedded w ithin your comment. These tags enable you to autogenerate a complete, w ell-formatted documentation from your source code.

XML comments are explained in detail

here

22 . For more detail see also

overview of commenting

19 .

Supported tags are:

XML Tag

<sum m ary>

111

<seealso>

116

<exam ple>

113

<typeparam >

114

<param >

114

<param ref>

116

<typeparam ref>

118

<returns>

112

<rem arks>

112

<author>

130

<version>

129

Meaning

Main description of member.

Specifies See Also list.

Specifies example.

Describes type parameter for generic member.

Describes function parameter.

Reference to parameter.

Reference to type parameter.

Describes return value.

Remarks.

Author.

Version.

© 2017 Helixoft

Comment Tags 111

<revision>

130

<include>

126

<includesource>

129

<com pilew hen>

127

<perm ission>

127

<threadsafety>

128

<exception>

115

user-defined

130

<value>

113

<para>

119

<code>

120

<c>

121

<see>

119

<list>

122

<im g>

123

<b>

124

<i>

124

<u>

125

<br>

125

<font>

123

See Also

Adding comments

19

6.1

<summary>

Revision date.

Includes comment from external XML file.

Whether to include source code in documentation.

Specifies compilation condition.

Documents the access of a member

Describe how a type behaves in multi-threaded scenarios.

Describes exception.

User-defined tags.

Value of property.

Paragraph.

Code block.

Inline code.

Inline link.

Bulleted or Numbered list or table.

Picture.

Bold.

Italic.

Undeline.

Line break, new line.

Font color.

The <summary> tag should be used to describe a type or a type member. Use

<remarks>

112 to add supplemental information to a type description.

The text for the <summary> tag is the only source of information about the type in IntelliSense, and is also displayed in the

Object Brow ser. This is a top-level tag.

Syntax

<summary>text</summary>

Examples

Visual Basic

''' <summary>Our sample property.</summary>

''' <remarks>This property is really interesting.</remarks>

''' <value>Some nice text.</value>

''' <seealso cref="TestDLL.DllClass1.prop2">Another interesting

''' property</seealso>

Property prop1() As String

C#

/// <summary>Our sample property.</summary>

/// <remarks>This property is really interesting.</remarks>

/// <value>Some nice text.</value>

/// <seealso cref="TestDLL.DllClass1.prop2">Another interesting

/// property</seealso>

© 2017 Helixoft

112 VSdocman Help public string prop1

See Also

Comment Tags

110

|

XML Comments

22

6.2

<remarks>

Specifies remarks. This is a top-level tag.

Syntax

<remarks> description</remarks>

Examples

Visual Basic

''' <summary>Our sample property.</summary>

''' <remarks>This property is really interesting.</remarks>

Property prop1() As String

C#

/// <summary>Our sample property.</summary>

/// <remarks>This property is really interesting.</remarks> public string prop1

See Also

XML Comments

22

6.3

<returns>

Describes the return value. This is a top-level tag.

Syntax

<returns>description<returns>

This tag is used in a method and function comment w hen they return some value. Use

<value>

113

tag for properties.

Examples

Visual Basic

''' <summary>Our sample method.</summary>

''' <returns>True if no error occurs.</returns>

Function method1(ByVal x As Integer) As Boolean

C#

/// <summary>Our sample method.</summary>

/// <returns>True if no error occurs.</returns> public bool method1(int x)

The sections in bold are added automatically w hen using Add XML Com m ent from pop-up menu.

See Also

XML Comments

22

© 2017 Helixoft

Comment Tags 113

6.4

<value>

The <value> tag is used to describe the value of a property. This is a top-level tag.

Syntax

<value>description</value>

By convention, properties should alw ays have a <value> tag.

For read-only properties, the text in the <value> tag w ill often be substantially the same as that in the <summary> tag.

Examples

Visual Basic

''' <summary>Our sample property.</summary>

''' <value>String containing our value.</value>

Property prop1() As String

C#

/// <summary>Our sample property.</summary>

/// <value>String containing our value.</value> public string prop1

The sections in bold are added automatically w hen using Add XML Com m ent from pop-up menu.

See Also

XML Comments

22

6.5

<example>

Creates an example section. This is a top-level tag.

Syntax

<example>example</example>

Your sample code should be enclosed w ithin

<code>

120 tags. You can use comment editor to do it.

Examples

Visual Basic

''' <summary>Our sample property.</summary>

''' <example>This is an example how to use prop1 and prop2 properties:

''' <code> Try

''' If Me.prop1 &lt;&gt; &quot;hello&quot; Then

''' prop2 = DllModule1.sampleEnum.value2

''' End If

''' Catch ex As nestedException

''' prop2 = DllModule1.sampleEnum.value1

''' End Try</code> </example>

Property prop1() As String

C#

/// <summary>Our sample property.</summary>

/// <example>This is an example how to use prop1 and prop2 properties:

/// <code> try {

/// if (this.prop1 != &quot;hello&quot;) {

/// prop2 = DllModule1.sampleEnum.value2;

/// }

© 2017 Helixoft

114 VSdocman Help

/// }

/// catch (nestedException ex) {

/// prop2 = DllModule1.sampleEnum.value1;

/// }</code> </example> public string prop1

See Also

<code> Tag

120

6.6

<param>

Adds a parameter description to the parameters section. This is a top-level tag. A comment may contain any number of

<param> tags.

Syntax

<param name="name">description</param> w here: name

The name of a method parameter. Enclose the name in quotation marks (" ").

description

A description for the parameter.

This tag is used in a method, function, property or event comment w hen some arguments are used.

Examples

Visual Basic

''' <summary>Sample method with two arguments.</summary>

''' <param name="x">The first parameter.</param>

''' <param name="y">The second parameter.</param>

Function method1(ByVal x As Integer, ByVal y As String) As Boolean

C#

/// <summary>Sample method with two arguments.</summary>

/// <param name="x">The first parameter.</param>

/// <param name="y">The second parameter.</param> public bool method1(int x, string y)

The text in bold is added automatically w hen using Add XML Com m ent from pop-up menu.

See Also

<typeparam> tag

114

6.7

<typeparam>

Adds a type parameter description to the type parameters section. This tag is only valid w hen used for generic member. This is a top-level tag. A comment may contain any number of <typeparam> tags.

Syntax

<typeparam name="name">description</param> w here:

© 2017 Helixoft

Comment Tags 115 name

The name of a type parameter. Enclose the name in quotation marks (" ").

description

A description for the type parameter.

This tag is used in generic members w hen type arguments are used.

Examples

Visual Basic

''' <summary>Represents a key-value pair which can be sorted.</summary>

''' <typeparam name="Tkey">Type of key which can be compared.</typeparam>

''' <typeparam name="Tvalue">Value type.</typeparam>

Public Class SortableKeyValuePair(Of Tkey As IComparable, Tvalue)

C#

/// <summary>Represents a key-value pair which can be sorted.</summary>

/// <typeparam name="Tkey">Type of key which can be compared.</typeparam>

/// <typeparam name="Tvalue">Value type.</typeparam> public class SortableKeyValuePair<Tkey, Tvalue> where Tkey : IComparable

The text in bold is added automatically w hen using Add XML Com m ent from pop-up menu.

See Also

<param> tag

114

6.8

<exception>

Adds a link into exceptions list. This tag lets you specify w hich exceptions a member can throw . This is a top-level tag. XML comment may contain any number of <exception> tags.

Syntax

<exception cref="reference">description</exception>

Reference should point to some Exception class in your project. Warning appears during compilation if reference points to non-existing target. Description describes situation w hen this exception is throw n.

Examples

Visual Basic

''' <exception cref="TestDLL.DllClass1.nestedException">

''' If something horrible happens.

</exception>

Function method1(ByVal x() As Integer, ByVal y As String) As Boolean

C#

/// <exception cref="TestDLL.DllClass1.nestedException">

/// If something horrible happens.

</exception> public bool method1(int[] x, string y)

See Also

Reference Format

© 2017 Helixoft

116 VSdocman Help

6.9

<seealso>

Adds a link into See Also list. This is a top-level tag. A comment may contain any number of <seealso> tags.

Syntax

<seealso cref="reference">[label]</seealso> or

<seealso href="reference">[label]</seealso>

It adds a link, w ith visible text label, that points to the documentation for the specified reference. Warning appears during compilation if reference points to non-existing target. The label is optional. If omitted, instead of it the reference appears as the visible text. Use the label w hen you w ant the visible text to be abbreviated or different from the reference. It can contain w hitespaces.

Examples

Visual Basic

''' <summary>Our sample property.</summary>

''' <remarks>This property is really interesting.</remarks>

''' <value>Some nice text.</value>

''' <seealso cref="TestDLL.DllClass1.prop2">Another interesting

''' property </seealso>

Property prop1() As String

C#

/// <summary>Our sample property.</summary>

/// <remarks>This property is really interesting.</remarks>

/// <value>Some nice text.</value>

/// <seealso cref="TestDLL.DllClass1.prop2">Another interesting

/// property </seealso> public string prop1

See Also

Reference Format |

XML Comments

22

6.10

<paramref>

The <paramref> tag gives you a w ay to indicate that a w ord in the code comments, for example in a <summary> or

<remarks> block refers to a parameter. This is usually displayed w ith italic font.

Syntax

<paramref name="name"/>

The name is the name of the parameter to refer to. Enclose the name in double quotation marks (" ").

Examples

Visual Basic

''' <summary>Method which compares the string representation

''' of <paramref name="x"/> parameter with string in <paramref name="y"/>

''' parameter.

</summary>

Function method1(ByVal x As Integer, ByVal y As String) As Boolean

C#

/// <summary>Method which compares the string representation

/// of <paramref name="x"/> parameter with string in <paramref name="y"/>

© 2017 Helixoft

Comment Tags 117

/// parameter.

</summary> public bool method1(int x, string y)

See Also

<typeparamref> Tag

118

|

XML Comments

22

6.11

<overloads>

The <overloads> tag specifies a summary, remarks and examples common to all overloads of a member. This information w ill appear on the Overloads topic page and on Members list topic page. This is a top-level tag.

Only one overload should specify this tag. If it's specified in several overloads, the random one w ill be chosen. Tw o forms of this tag are available. The short form only contains common summary text for all overloads. It w ill appear on the Overloads topic page and on Members list topic page. In expanded form, you can add tw o more tags inside it - remarks and example.

This information w ill appear on the Overloads topic page.

Syntax

Short form:

<overloads>summary_text</overloads>

Expanded form:

<overloads>

<summary>summary_text</summary>

[<remarks>remarks_text</remarks>]

[<example>example_text</example>]

</overloads>

Examples

Short form:

Visual Basic

''' <summary>Our sample method with parameter.</summary>

''' <param name="x">The first parameter.</param>

''' <overloads>

''' Common summary. This method has two overloads.

''' </overloads>

Sub method1(ByVal x As Integer)

''' <summary>Our sample method without parameter.</summary>

Sub method1()

C#

/// <summary>Our sample method with parameter.</summary>

/// <param name="x">The first parameter.</param>

/// <overloads>

/// Common summary. This method has two overloads.

/// </overloads> public void method1(int x)

/// <summary>Our sample method without parameter.</summary> public void method1()

Expanded form:

Visual Basic

''' <summary>Our sample method with parameter.</summary>

© 2017 Helixoft

118 VSdocman Help

''' <param name="x">The first parameter.</param>

''' <remarks>Remarks text just for this overload with one parameter.</remarks>

''' <overloads>

''' <summary>

''' Common summary. This method has two overloads.

''' </summary>

''' <remarks>

''' Common remarks text.

''' </remarks>

''' <example>

''' Common example text.

''' </example>

''' </overloads>

Sub method1(ByVal x As Integer)

''' <summary>Our sample method without parameter.</summary>

Sub method1()

C#

/// <summary>Our sample method with parameter.</summary>

/// <param name="x">The first parameter.</param>

/// <overloads>

/// <summary>

/// Common summary. This method has two overloads.

/// </summary>

/// <remarks>

/// Common remarks text.

/// </remarks>

/// <example>

/// Common example text.

/// </example>

/// </overloads> public void method1(int x)

/// <summary>Our sample method without parameter.</summary> public void method1()

See Also

Comment Tags

110 |

XML Comments

22

6.12

<typeparamref>

The <typeparamref> tag gives you a w ay to indicate that a w ord in the code comments, for example in a <summary> or

<remarks> block refers to a type parameter. This is usually displayed w ith italic font.

Syntax

<typeparamref name="name"/>

The name is the name of the type parameter to refer to. Enclose the name in double quotation marks (" ").

Examples

Visual Basic

''' <summary>Represents a key-value pair where the key

''' is of type <typeparamref name="Tkey"> and can be sorted.</summary>

© 2017 Helixoft

Comment Tags 119

Public Class SortableKeyValuePair(Of Tkey As IComparable, Tvalue)

C#

/// <summary>Represents a key-value pair where the key

/// is of type <typeparamref name="Tkey"> and can be sorted.</summary> public class SortableKeyValuePair<Tkey, Tvalue> where Tkey : IComparable

See Also

<paramref> Tag

116

|

XML Comments

22

6.13

<para>

The <para> tag is for use inside a tag, such as

<summary>

paragraph to the text.

111

, <remarks>

112

, or

<returns>

112

, and lets you add

Syntax

<para>text</para>

Examples

Visual Basic

''' <summary>Our sample property.

''' <para>This is new paragraph</para>

''' </summary>

Property prop1() As String

C#

/// <summary>Our sample property.

/// <para>This is new paragraph</para>

/// </summary> public string prop1

See Also

Comment Tags

110 |

XML Comments

22

6.14

<see>

The <see> tag lets you specify a link from w ithin text. Use

<seealso>

116

to indicate text that you might w ant to appear in a

See Also section. The <see> tag can be also used to include language keyw ord in the text.

Syntax

<see cref="reference">[label]</see> or

<see href="reference">[label]</see> or

<see langword="keyword"/>

The first syntax adds a link, w ith visible text label, that points to the documentation for the specified reference. Warning appears during compilation if reference points to non-existing target. The second syntax adds a link, w ith visible text label, that points to an external resource, e.g. local file or internet URL. The label is optional. If omitted, instead of it the reference appears as the visible text. Use the label w hen you w ant the visible text to be abbreviated or different from the reference. It can contain w hitespaces.

© 2017 Helixoft

120 VSdocman Help

The last syntax allow s adding the language keyw ord. The localized text w ith keyw ord is inserted in documentation in the place of this tag. The follow ing table lists allow ed values of langw ord parameter and a corresponding (English) text: langw ord null true false static abstract sealed virtual

Examples

Text null reference (Nothing in Visual Basic) true false static (Shared in Visual Basic) abstract (MustInherit in Visual Basic) sealed (NotInheritable in Visual Basic) virtual (Overridable in Visual Basic)

Visual Basic

''' <summary>Our sample property.</summary>

''' <remarks>

''' This is link to <see cref="TestDLL.DllClass1.prop2"></see>.

''' This is <see cref="TestDLL.DllClass1.prop2">the same link</see>.

''' This is link to <see href="myfile.html">an external file</see>.

''' Initial value of this property is <see langword="null"/>.

''' </remarks>

Property prop1() As String

C#

/// <summary>Our sample property.</summary>

/// <remarks>

/// This is link to <see cref="TestDLL.DllClass1.prop2"></see>.

/// This is <see cref="TestDLL.DllClass1.prop2">the same link</see>.

/// This is link to <see href="myfile.html">an external file</see>.

/// Initial value of this property is <see langword="null"/>.

/// </remarks> public string prop1

See Also

Comment Tags

110 |

XML Comments

22 |

<seealso> Tag

116 | Reference Format

6.15

<code>

The <code> tag gives you a w ay to indicate multiple lines as code. Use

<c>

121

to indicate that text w ithin a description should be marked as a code.

Syntax

<code lang="C#|VB">text</code>

The lang attribute is optional. It has tw o allow ed values - VB and C#. Alternative values for C# are csharp and cs (case insensitive). Alternative values for VB are VB.NET and vbnet (case insensitive). If the lang attribute is omitted, the code is general. If specified, the code is marked as C# or Visual Basic and can be filtered w ith language filter.

Examples

Visual Basic

''' <summary>Our sample property.</summary>

''' <example>This is an example how to use prop1 and prop2 properties:

© 2017 Helixoft

Comment Tags 121

''' <code> Try

''' If Me.prop1 &lt;&gt; &quot;hello&quot; Then

''' prop2 = DllModule1.sampleEnum.value2

''' End If

''' Catch ex As nestedException

''' prop2 = DllModule1.sampleEnum.value1

''' End Try </code></example>

Property prop1() As String

C#

/// <summary>Our sample property.</summary>

/// <example>This is an example how to use prop1 and prop2 properties:

/// <code> try {

/// if (this.prop1 != &quot;hello&quot;) {

/// prop2 = DllModule1.sampleEnum.value2;

/// }

/// }

/// catch (nestedException ex) {

/// prop2 = DllModule1.sampleEnum.value1;

/// } </code></example> public string prop1

Note

Remember that XML comments must be a w ell-formed XML. Therefore some characters cannot be used in an attribute or a tag value. Those characters often appear in the source code so you have to be careful especially w hen using <code> or

<c>

121

tags. You must escape the follow ing characters:

Character quote (") apostrophe (') ampersand (&) less than (<) greater than (>)

Escape sequence

&quot;

&apos;

&amp;

&lt;

&gt;

Or if the code is longer, you can use <![CDATA[ ... ]]>. This is w hat comment editor does. The code is then more readable.

The safest w ay to enter these characters is to use VSdocman

WYSIWYG comment editor

131 .

See Also

<c> tag

121

|

$CODE$ macro

31

6.16

<c>

The <c> tag gives you a w ay to indicate that text w ithin a description should be marked as code. Use

<code>

120

to indicate multiple lines as code.

Syntax

<c>constant</c>

Examples

Visual Basic

''' <summary> <c>Prop1</c> is our sample property.</summary>

Property prop1() As String

C#

© 2017 Helixoft

122 VSdocman Help

/// <summary> <c>Prop1</c> is our sample property.</summary> public string prop1

See Also

<code> tag

120

| $CODE$ macro

31

6.17

<list>

The <list> tag describes a numbered or bulleted list, a definition list or a table.

Syntax

<list type="bullet" | "number" | "table">

<listheader>

<term>term</term>

<description>description</description>

</listheader>

<item>

<term>term</term>

<description>description</description>

</item>

</list>

The <listheader> block is used to define the heading row of a table.

Each item in the list is specified w ith an <item> block. When creating a definition list, you w ill need to specify both term and description. How ever, for a table, bulleted list, or numbered list, you only need to supply an entry for description.

A list or table can have as many <item> blocks as needed. Normally, the table can have only one column (using <term>) or tw o columns (using <term> and <description>). But you can extend this syntax and

create the table w ith more columns

32 .

Examples

Visual Basic

''' <summary>Our sample property.</summary>

''' <remarks>This property is really interesting. We can use:

''' <list type="number">

''' <item>

''' <description>font formatting or code</description></item>

''' <item>

''' <description>bulleted or numbered lists</description></item>

''' <item>

''' <description>tables, pictures and links</description></item>

''' </list>

''' </remarks>

Property prop1() As String

C#

/// <summary>Our sample property.</summary>

/// <remarks>This property is really interesting. We can use:

/// <list type="number">

/// <item>

/// <description>font formatting or code</description></item>

/// <item>

/// <description>bulleted or numbered lists</description></item>

/// <item>

/// <description>tables, pictures and links</description></item>

/// </list>

/// </remarks>

© 2017 Helixoft

Comment Tags 123 public string prop1

See Also

Comment Tags

110

|

XML Comments

22

6.18

<img>

The <img> tag is for use inside a tag, such as <summary>

111 ,

<remarks>

112 , or

<returns>

112 , and lets you add an image or a class diagram to the text. Image or diagram w ill appear in resulting documentation on the place of <img> tag, exactly like this logo.

All im age files (except class diagram s) should be located in your folder for

external files

27 .

To insert class diagram, you specify its .cd file w ith path relative to the project root path. The best w ay is to use

comment editor

131

.

Syntax

<img src="image_file_name|class_diagram_file_name" />

Examples

Visual Basic

''' <summary>Our sample property.</summary>

''' <remarks>

''' Here we have picture <img src="subFolder/myPicture.png" />

''' Here we have class diagram <img src="ClassDiagram1.cd"/>

''' </remarks>

Property prop1() As String

C#

/// <summary>Our sample property.</summary>

/// <remarks>

/// Here we have picture <img src="subFolder/myPicture.png" />

/// Here we have class diagram <img src="ClassDiagram1.cd"/>

/// </remarks> public string prop1

See Also

Comment Tags

110

|

XML Comments

22 |

Adding Images in Documentation

31

6.19

<font>

The <font> tag is for use inside a tag, such as

<summary>

111

, <remarks>

112 , or

<returns>

of the text.

112 , and lets you specify a color

Syntax

<font color="color">text</font>

Examples

© 2017 Helixoft

124 VSdocman Help

Visual Basic

''' <summary>Our sample property.</summary>

''' <remarks>This text is <font color="#FF0000">red</font>

Property prop1() As String

C#

/// <summary>Our sample property.</summary>

/// <remarks>This text is <font color="#FF0000">red</font> public string prop1

See Also

Comment Tags

110

|

XML Comments

22

6.20

<b>

The <b> tag is for use inside a tag, such as

<summary>

111

, <remarks>

112 , or

<returns>

112 , and lets you add bold text.

Syntax

<b>text</b>

Examples

Visual Basic

''' <summary>Our sample property.

''' <b>This is bold</b>

''' </summary>

Property prop1() As String

C#

/// <summary>Our sample property.

/// <b>This is bold</b>

/// </summary> public string prop1

See Also

Comment Tags

110 |

XML Comments

22

6.21

<i>

The <i> tag is for use inside a tag, such as

<summary>

111 ,

<remarks>

112 , or

<returns>

112 , and lets you add italic text.

Syntax

<i>text</i>

Examples

Visual Basic

''' <summary>Our sample property.

''' <i>This is italic</i>

''' </summary>

Property prop1() As String

C#

© 2017 Helixoft

Comment Tags 125

/// <summary>Our sample property.

/// <i>This is italic</i>

/// </summary> public string prop1

See Also

Comment Tags

110

|

XML Comments

22

6.22

<u>

The <u> tag is for use inside a tag, such as

<summary>

text.

111

, <remarks>

112

, or

<returns>

112

, and lets you add underlined

Syntax

<u>text</u>

Examples

Visual Basic

''' <summary>Our sample property.

''' <u>This is underlined</u>

''' </summary>

Property prop1() As String

C#

/// <summary>Our sample property.

/// <u>This is underlined</u>

/// </summary> public string prop1

See Also

Comment Tags

110 |

XML Comments

22

6.23

<br>

The <br> tag is for use inside a block tag, such as

<summary>

111 break. You can press SHIFT+ENTER in comment editor to insert it.

, <remarks>

112 , or

<returns>

112 , and lets you add a line

Syntax

<br/>

Examples

Visual Basic

''' <summary>Our sample property.

<br/>

''' This is on a new line .

''' </summary>

Property prop1() As String

C#

/// <summary>Our sample property.

<br/>

/// This is on a new line .

/// </summary> public string prop1

© 2017 Helixoft

126 VSdocman Help

See Also

Comment Tags

110

|

XML Comments

22

6.24

<include>

The <include> tag lets you refer to comments in another file that describe the types and members in your source code. This is an alternative to placing documentation comments directly in your source code file. By putting the documentation in a separate file, you can apply source control to the documentation separately from the source code. One person can w ork on the source code file and someone else can w ork on the documentation file.

The <include> tag uses the XML XPath syntax. Refer to XPath documentation for w ays to customize your <include> use. This is a top-level tag.

Syntax

<include file="filename" path="tagpath[@name='id']" /> w here: filename

The name of the XML file containing the documentation. The file name can be qualified w ith a path.

tagpath

The path of the tags in filename that leads to the tag name.

name

The name specifier (attribute) in the tag that precedes the comments; name w ill have an id. id

The ID for the tag that precedes the comments. It should be a member full identifier in cref syntax.

Examples

Let's have the follow ing XML comments in a source code:

Visual Basic

''' <summary>Our sample property.</summary>

''' <include file="external_comments.xml"

''' path="doc/members/member[@name='P:TestDLL.DllClass1.prop1']/*" />

Property prop1() As String

C#

/// <summary>Our sample property.</summary>

/// <include file="external_comments.xml"

/// path="doc/members/member[@name='P:TestDLL.DllClass1.prop1']/*" /> public string prop1

The external_comments.xml file contains the follow ing:

Exam ple

<?xml version="1.0" encoding="utf-8"?>

<doc>

<members>

<member name="P:TestDLL.DllClass1.prop1">

<remarks>

This are remarks for prop1.

</remarks>

© 2017 Helixoft

Comment Tags 127

</member>

<member name="P:TestDLL.DllClass1.prop2">

<remarks>

This are remarks for prop2.

</remarks>

</member>

</members>

</doc>

Then resulting XML comment for prop1 property w ill be:

Exam ple

<summary>Our sample property.</summary>

<remarks>

This are remarks for prop1.

</remarks>

See Also

Conditional Compilation Options

53

6.25

<compilewhen>

Specifies w hen a member should be included in the documentation. The member w ill be only compiled w hen a constant specified in this tag is also listed in

Code Members-Conditional Compilation

53 options. If <compilew hen> tag is not specified, the member is alw ays included. This is a top-level tag.

Syntax

<compilewhen>constant</compilewhen>

Examples

Visual Basic

''' <summary>Our sample property.</summary>

''' <compilewhen>internal</compilewhen>

Property prop1() As String

C#

/// <summary>Our sample property.</summary>

/// <compilewhen>internal</compilewhen> public string prop1

See Also

Conditional Compilation Options

53

6.26

<permission>

This tag lets you document the access of a member. This is a top-level tag w hich may be used multiple times in an XML comment.

Syntax

<permission cref="member">description</permission> w here: member

© 2017 Helixoft

128 VSdocman Help

A reference to a member or field that is available to be called from the current compilation environment. You most probably w ill insert the reference to the Perm issionSet class w hich lets you specify access to a member.

description

A description of the access to the member.

Examples

Visual Basic

''' <summary>Our sample method.</summary>

''' <permission cref="System.Security.PermissionSet">

''' Everyone can access this method.</permission>

Public Sub Method1()

C#

/// <summary>Our sample method.</summary>

/// <permission cref="System.Security.PermissionSet">

/// Everyone can access this method.

</permission> public void Method1()

See Also

XML Comments

22

6.27

<threadsafety>

This tag is used to describe how a class or structure behaves in multi-threaded scenarios. This is a top-level tag w hich may be used only in a class or structure.

Syntax

<threadsafety static="true|false" instance="true|false"/> or

<threadsafety static="true|false" instance="true|false">custom text</threadsafety> w here: static="true|false"

Indicates w hether any static (Shared in Visual Basic) members of this type are thread safe.

instance="true|false"

Indicates w hether any instance members of this type are thread safe.

custom text

If specified, the static and instance attributes are ignored and the text w ill be show n in generated documentation.

Examples

Visual Basic

''' <summary>Our sample class.</summary>

''' <threadsafety static="true" instance="false"/>

Public Class Class1

C#

/// <summary>Our sample class.</summary>

/// <threadsafety static="true" instance="false"/> public class Class1

© 2017 Helixoft

Comment Tags 129

See Also

XML Comments

22

6.28

<includesource>

Specifies w hether the source code should be included in documentation. It has only meaning if Include source code in

docum entation option is set to According to sourcecode tag in

Source code options

61 . If it contains non em pty

string, the code w ill be included, otherw ise (if not used) not. This is a top-level tag.

Syntax

<includesourcecode>yes</includesourcecode>

Examples

Visual Basic

''' <summary>Our sample property.</summary>

''' <includesource>yes</includesource>

Property prop1() As String

C#

/// <summary>Our sample property.</summary>

/// <includesource>yes</includesource> public string prop1

See Also

Source code options

61

6.29

<version>

Specifies a version. This is a top-level tag.

Syntax

<version>version</version>

Examples

Visual Basic

''' <summary>Our sample property.</summary>

''' <version>1.0</version>

Property prop1() As String

C#

/// <summary>Our sample property.</summary>

/// <version>1.0</version> public string prop1

See Also

XML Comments

22

© 2017 Helixoft

130 VSdocman Help

6.30

<revision>

Specifies a revision number or a date. This is a top-level tag.

Syntax

<revision>revision</revision>

Examples

Visual Basic

''' <summary>Our sample property.</summary>

''' <revision>23</revision>

Property prop1() As String

C#

/// <summary>Our sample property.</summary>

/// <revision>23</revision> public string prop1

See Also

<version>

129

6.31

<author>

Specifies an author. This is a top-level tag.

Syntax

<author>author</author>

Examples

Visual Basic

''' <summary>Our sample property.</summary>

''' <author>Peter Macej</author>

Property prop1() As String

C#

/// <summary>Our sample property.</summary>

/// <author>Peter Macej</author> public string prop1

See Also

<version>

129

6.32

User-defined

User defined tags. The names <user1>, <user2>, ..., <userN> are their default names and they can be changed by a user.

These tags are top-level tags in an XML comment and they cannot be nested inside other tags. You can create your ow n topic sections w ith them. They can be used for any purpose and their syntax and usage is the same as e.g.

<remarks>

tag. You can define unlimited number of such tags.

112

User defined fields have the same format as Remarks and by default they are show n at the end of topic under Remarks. If they are used and you w ant them appear on some other place, you need to edit output templates. Additionally, you can

predefine a default text

74 for each user tag. This text w ill be used w hen you place an empty user tag in the comment.

© 2017 Helixoft

7

Comment Tags 131

Syntax

<user1>description<user1>

Examples

User has defined one tag as copyright and one tag as todo.

Visual Basic

''' <copyright>(c) 2017 Helixoft</copyright>

''' <todo>Improve exception handling</todo>

Property prop1() As String

C#

/// <copyright>(c) 2017 Helixoft</copyright>

/// <todo>Improve exception handling</todo> public string prop1

See Also

Templates

142

| Macro Language

144

| User Tags Options

74 |

XML Comments

22

Comment Editor

VSdocman Comment Editor is a WYSIWYG tool for editing XML comments. Editor recognizes both XML and old deprecated @style javadoc comments but it can only produce XML comments. VSdocman comments can be edited directly in a source code but sometimes this can be a difficult task. For example using <list> or <seealso> tags can lead to errors. Even w ith simple comments it is not comfortable to update them w hen something has changed.

Comment editor can significantly help in documentation process. It allow s to edit comments w ithout any know ledge of XML tags and it assures consistency w ith actual source code state as w ell. With comment editor, user can easily edit all fields in a comment, automatically update changed parameters of methods, select available cross-references from a list and so on.

Editor reads your comments and at the end (by pressing OK or Apply button) it w rites the changes back into the source code comments. Thus you can combine manual and graphical comment editing as you w ant. Comment editor alw ays produces correct output and it may reorder your tags w ritten manually. This how ever, does not affect the final documentation. If the Comment editor is invoked on a member w ithout VSdocman comment, it is automatically filled by default

XML comment for that object, as defined in

comment templates

75 .

To invoke Com m ent Editor

In the code w indow select the object you w ant to document. Click right mouse button, the pop-up menu appears. Press

Com m ent Editor item to start Comment editor.

© 2017 Helixoft

132 VSdocman Help

You can sw itch betw een WYSIWYG view and classical view w ith WYSIWYG button.

See Also

Comment Editor - WYSIWYG

133

| Comment Editor - Advanced

Parameters

136 |

Comment Editor - References

137

134

|

Comment Editor - General

135

| Comment Editor -

|

Comment Editor - Example

139 |

Comment Editor - Misc

140

| Comment

Editor - User fields

141

| Comment Editor - Source code view

142

© 2017 Helixoft

7.1

WYSIWYG

Start

VSdocm an Com m ent Editor

131

and select WYSIWYG tab.

Comment Editor 133

This is the most user-friendly editor mode w here you can edit almost everything in WYSIWYG style. Document is divided to editable areas w here you can edit your text, tables and pictures. You can paste or drag&drop formatted HTML text including images, drag&drop image files, select editor font size and much more.

Editable areas represent various parts of documentation such as a summary, remarks, etc. You can highlight borders of editable areas w ith button on toolbar.

You can easily add new sections w ith button on toolbar. Move among sections w ith TAB and SHIFT+TAB shortcuts.

Use toolbar buttons at the top, context menu or keyboard shortcuts to format, add or delete objects.

You can sw itch betw een WYSIWYG and classical mode using WYSIWYG button. Changes in any mode w ill be automatically applied to other mode.

See Also

© 2017 Helixoft

134 VSdocman Help

VSdocman Comment Editor

131

7.2

Advanced

Start

VSdocm an Com m ent Editor

131

and select Advanced tab.

Include source code

Corresponds to

<includesource>

129 tag.

Com pile only w hen the follow ing constant is defined...

Corresponds to

<compilew hen>

127 tag. Leave blank if this member should be alw ays compiled. If you enter a constant name here, the member w ill be only compiled w hen the constant specified in this field is also listed in

Code Members-Conditional

Compilation

53 options.

Thread Safety...

Corresponds to

<threadsafety>

128

tag.

Include com m ents from external XML files

Corresponds to

<include>

126

tags. You can refer to comments in another file(s) here.

See Also

VSdocman Comment Editor

131

|

<includesource> tag>

129

| <compilew hen> tag

127

|

<include> tag

126

© 2017 Helixoft

Comment Editor 135

7.3

General

Start

VSdocm an Com m ent Editor

131

, uncheck WYSIWYG button and select General tab.

This dialog allow s to edit basic fields of member's documentation.

Description

Corresponds to

<summary>

111 tag.

Rem arks

Corresponds to

<remarks>

112 tag.

See Also

VSdocman Comment Editor

131

© 2017 Helixoft

136 VSdocman Help

7.4

Parameters

Start

VSdocm an Com m ent Editor

131

, uncheck WYSIWYG button and select Param eters tab.

This dialog allow s to edit description of parameters, type parameters and return value of the member. This dialog is enabled only w hen applicable (methods, properties and events or generic members).

Param eters

This section is used for editing parameters. Editor automatically updates all fields in this tab to their actual values. That means that all non-existing parameters mentioned in a comment are removed from the list as w ell as their descriptions, if any.

Similarly, all new parameters not listed are added w ith their default description.

Param eter nam e

List of actual parameters. Selecting some parameter from this list affects the content of the Description field.

Description

Description of selected parameter. This field together w ith Param eter nam e field corresponds to

<param>

114 tag.

Returns

Describes the return value. Corresponds to

<return>

112 or

<value>

113 tag.

Type Param eters

This section is used for editing type parameters of generics. Editor automatically updates all fields in this tab to their actual values. That means that all non-existing type parameters mentioned in a comment are removed from the list as w ell as their descriptions, if any. Similarly, all new type parameters not listed are added.

© 2017 Helixoft

Comment Editor 137

Param eter nam e

List of actual type parameters. Selecting some parameter from this list affects the content of the Description field.

Description

Description of selected type parameter. This field together w ith Param eter nam e field corresponds to

<typeparam>

114

tag.

See Also

VSdocman Comment Editor

131

7.5

References

Start

VSdocm an Com m ent Editor

131

, uncheck WYSIWYG button and select References tab.

This dialog allow s to edit all references that may appear in the member's documentation. User is not required to know the link syntax, target members may be selected by dialog.

© 2017 Helixoft

138 VSdocman Help

See Also

Edit See also links. Corresponds to

<seealso>

116

tag. Use Add and Rem ove buttons to add new link or delete selected one from the list on the left.

Link

The target of the link as specified in <seealso> syntax. There's a button that invokes Select reference dialog. User can select the target from the list, w hether the member in the project or external file.

Label

Link label show n in documentation. See the

<seealso>

116 syntax.

Find interesting references

This button brings some intelligence to the comment editor. When you press it, editor automatically show s a list of suggested links that might appear in See Also section. You can then select w hich are to be inserted. VSdocman looks for implemented interfaces or interface implementing classes, argument types of current method or types used inside current method.

Exceptions

Edit Exceptions table. Corresponds to

<exception>

115

tag. Use Add and Rem ove buttons to add new link or delete selected one from the list on the left.

Link

The the link to exception as specified in <exception> syntax. There's a button that invokes Select reference dialog. User can select the target from the list.

Description

Description of exception. See the

<exception>

115 syntax.

See Also

VSdocman Comment Editor

131

|

<exception> tag

115

|

<seealso> tag

116

© 2017 Helixoft

Comment Editor 139

7.6

Example

Start

VSdocm an Com m ent Editor

131

, uncheck WYSIWYG button and select Exam ple tab.

This dialog allow s to edit example in member's documentation.

Exam ple

Corresponds to

<example>

113 tag.

See Also

VSdocman Comment Editor

131

© 2017 Helixoft

140 VSdocman Help

7.7

Misc

Start

VSdocm an Com m ent Editor

131

, uncheck WYSIWYG button and select Misc tab.

This dialog allow s to edit miscellaneous fields of member's documentation.

Author

Corresponds to

<author>

130

tag.

Version

Corresponds to

<version>

129

tag.

Revision

Corresponds to

<revision>

130

tag.

Include source code

Corresponds to

<includesource>

129

tag.

Com pile only w hen the follow ing constant is defined...

Corresponds to

<compilew hen>

127

tag. Leave blank if this member should be alw ays compiled. If you enter a constant name here, the member w ill be only compiled w hen constant specified in this field is also listed in

Code Members-Conditional

Compilation

53 options.

See Also

VSdocman Comment Editor

131

© 2017 Helixoft

Comment Editor 141

7.8

User-defined fields

Start

VSdocm an Com m ent Editor

131

, uncheck WYSIWYG button and select User fields tab.

This dialog allow s to edit user-defined fields (tags) of member's documentation.

Fields

A list of all user-defined tags. They correspond to

user-defined

130

tags (copyright, todo and diagram in the figure above).

User field text

A value of selected user tag for current code member.

See Also

VSdocman Comment Editor

131

© 2017 Helixoft

142 VSdocman Help

7.9

Source code view

Start

VSdocm an Com m ent Editor

131

and select Source code view tab.

8

This dialog is read-only and show s how the resulting XML comment w ill look like. This comment w ill be attached to the member in a source code after pressing OK or Apply button.

See Also

VSdocman Comment Editor

131

VSdocman Templates

8.1

Templates

VSdocman uses special files called templates to generate its output. A template defines the format of this output. VSdocman comes w ith some predefined templates for generating documentation in the follow ing formats:

·

CHM

·

HTML

·

docx - OOXML format used in MS Word 2007 and higher

·

MS Help View er - help used in VS 2010 and higher

·

Help2 - help used in VS 2002-2008

·

XML

These templates are files w ith .vbdt extension and are located in VSdocman\Templates folder by default.

© 2017 Helixoft

VSdocman Templates 143

How ever, you can define your ow n template to customize the output. It is possible to define almost any text based document.

A simple

macro language

144

w as developed that enables you to change the output settings.

See Also

Macro Language

144

| Output Options

55 |

Editing the Output Templates

143

8.2

Editing the Output Templates

The output templates (.vbdt files) are just plain text files w ith a simple macro syntax. You can edit them in any text editor, including Visual Studio.

The .vbdt files use very simple syntax but the entire template code may look quite messy. It may be difficult to navigate in it, if there's no syntax highlighting.

Starting w ith Visual Studio 2015, you can create custom syntax highlighters for your ow n file types. This is thanks to the

Visual Studio Extension for TextMate Gram m ars w hich is a part of the VS installation by default. VSdocman comes w ith the syntax highlighter for .vbdt files. If you need to customize the templates, you can install the highlighter and then edit the .vbdt files in Visual Studio comfortably.

To install the .vbdt gram m ar:

1.

Close Visual Studio.

2.

Go to C:\Program Files (x86)\VSdocm an\Tem plates\Vbdt editing\ folder. There's vbdt subfolder inside it.

© 2017 Helixoft

144 VSdocman Help

3.

Copy the vbdt subfolder to C:\Users\<USERNAME>\.vs\Extensions\ folder. This is the folder w ith the TextMate extension grammars.

Note: If you have the Syntax Highlighting Pack extension installed in your Visual Studio, it w ill rew rite the C:

\Users\<USERNAME>\.vs\Extensions\ folder. To make the grammar w ork, you need to do the follow ing:

Find the Syntax Highlighting Pack extension's directory in the local AppData folder. The extensions root folder should be like C:\Users\<USERNAME>\AppData\Local\Microsoft\VisualStudio\14.0\Extensions\, w here 14.0

is for VS 2015 and 15.0_XY is for VS 2017.

There are many subfolders w ith cryptic names, find the correct one by searching for

Textm ateBundleInstaller.pkgdef file. For example, you'll find it in C:

\Users\<USERNAME>\AppData\Local\Microsoft\VisualStudio\14.0\Extensions\htm rdfpe.z35. Copy the

vbdt subfolder w ith the grammar to Bundles subfolder in the folder you found, e.g. to: C:

\Users\<USERNAME>\AppData\Local\Microsoft\VisualStudio\14.0\Extensions\htm rdfpe.z35\Bundles\.

4.

Delete languages.cache and (if exists) Syntax Highlighting Pack.log files in C:

\Users\<USERNAME>\.vs\Extensions\.

Now you can start Visual Studio, open a .vbdt file and you should see its syntax highlighted.

Note: In VS 2015, the Visual Studio Extension for TextMate Gram m ars doesn't support VS color schemes. In VS 2017, this is supported and the colors from the VS settings are used.

8.3

Macro Language

Templates are simple ASCII files containing only comments and macro definitions. Comment is any text that is outside any macro definition. It is recommended to w rite a quote at the beginning of each comment line. Macro language is case sensitive.

Macro definition has tw o forms. Every macro name is embedded betw een tw o "$" characters e.g. $this-is-m acro-nam e$.

If macro name is used inside any macro definition it is treated as an expansion of macro w ith specified name.

Macro definition starts w ith a macro name w hich must be at the beginning of the line. If the macro name does NOT start w ith

"$vbdoc-" string, its definition continues only on that line.

The follow ing defines a macro w hose value is ".html".

Exam ple

$MEMBER-EXT$ .html

If the macro name starts w ith "$vbdoc-" string (thus complete name is "$vbdoc-rest"), its definition is all the follow ing text until the first occurrence of "$end-vbdoc-rest" string w hich also must be at the beginning of the line.

Exam ple

$vbdoc-description$

Creates HTML Help (*.chm) file which looks like MSDN Visual Basic Reference.

Links in related topics are displayed as pop-up dialogs. Temporary HTML files are also created and can be edited later. Then they can be compiled by hhc.exe program located in $VBDOC-PATH$\Templates directory.

$end-vbdoc-description$

Macro body can contain any ASCII text or expansion of another macro by simple inserting its name. In the previous example, the macro expansion is marked w ith red color. Whenever the $vbdoc-description$ macro is expanded, its body replaces macro call and all macro expansions (calls) inside its body are expanded as w ell.

System takes every occurrence of "$" character in any macro body as a start of a macro call. There must be also terminating

"$" character, otherw ise an error occurs. If there is a macro call to an undefined macro, nothing is expanded and that macro call is supposed to be normal ASCII text. If you w ant to use "$" character in the macro, you must w rite it tw ice: "$$". Then the system know s that it is not macro call and replaces it w ith one "$".

Exam ple

$price$ 10

© 2017 Helixoft

VSdocman Templates 145

$vbdoc-sentence$

The price for the taxi is $$$price$

$end-vbdoc-sentence$

Result of expanding $vbdoc-sentence$ macro is "The price for the taxi is $10".

User can define his ow n macros but some macros are fixed and provided by VSdocman:

1.

Read-only macros

145

, their values are set by VSdocman during compilation.

2.

Compulsory macros

150

that must be defined by user in a template because VSdocman uses them w hile compiling.

3.

Commands

152

that are used to make loops and conditions.

The best w ay to learn how to use them is to read predefined template files (*.vbdt) in VSdocman\Templates folder.

See Also

VSdocman Templates

142

| Read-only macros

Templates

143

145

|

Compulsory macros

150

| Commands

152

|

Editing the Output

8.3.1

Read-only Macros

Their values are set by VSdocman during compilation and user cannot redefine them. Note, links in all lists are sorted alphabetically.

Macro

$VBDOC-PATH$

$OUTPUT-PATH$

$EXTERNAL-FILES-LIST$

$EXTERNAL-FILES-PATH$

$TEMPLATE-PATH$

$PROJECT-NAME$

$PROJECT-NAME-SAFE$

$SOLUTION-NAME$

$SOLUTION-NAME-SAFE$

$HXCOMP-PATH$

$CUSTOM-VAR1$

$CUSTOM-VAR2$

$CUSTOM-VAR3$

$NEXT-ID$

$COUNTER$

$SEE-LINK-LIST$

$PROPS-LINK-LIST$

$METHODS-LINK-LIST$

$EXTENSION-METHODS-LINK-LIST$

Meaning

Specifies path w here VSdocman is installed. It is alw ays w ithout "\" at the end.

Specifies output directory for generated documentation. It is alw ays w ithout "\" at the end.

List of external files from external files folder.

Specifies directory for external files. It is alw ays w ithout "\" at the end.

Specifies template directory currently used. It is alw ays w ithout "\" at the end.

The name of current project.

The name of current project. All non-alphanumeric characters are replaced by underscore.

The name of current solution.

The name of current solution. All non-alphanumeric characters are replaced by underscore.

Path to hxcomp.exe including the file itself.

Any custom text editable from

VSdocman's dialog

84 .

Any custom text editable from

VSdocman's dialog

84 .

Any custom text editable from

VSdocman's dialog

84 .

Unique number w ithin w hole document.

Value of internal counter.

List of See Also links. It can be used only w ithin DOLIST macro. Every link consists of several

fields

148

.

List of links pointing to all properties in current member. It can be used only w ithin DOLIST macro. Every link consists of several

fields

148

.

List of links pointing to all methods in current member. It can be used only w ithin DOLIST macro. Every link consists of several

fields

148 .

List of links pointing to all extension methods in current member. It can be used only w ithin DOLIST macro. Every link consists of several

fields

148

.

© 2017 Helixoft

146 VSdocman Help

$CONSTRUCTORS-LINK-LIST$

$EVENTS-LINK-LIST$

$NAMESPACES-LINK-LIST$

$STRUCTURES-LINK-LIST$

$INTERFACES-LINK-LIST$

$DELEGATES-LINK-LIST$

$ENUMS-LINK-LIST$

$FORMS-LINK-LIST$

$OBJECTS-LINK-LIST$

$STDMODULES-LINK-LIST$

$VARS-LINK-LIST$

$CONSTANTS-LINK-LIST$

$SUPERCLASSES-LINK-LIST$

$SUBCLASSES-LINK-LIST$

$OVERLOAD-LINK-LIST$

$APPLIES-LINK-LIST$

$INDEX-LINK-LIST$

$CUSTOM-TOPICS-LINK-LIST$

$TYPE-PARAM-LIST$

$PARAM-LIST$

$EXCEPTIONS-LIST$

$SET01-LIST$

List of links pointing to all constructors in current member. It can be used only w ithin DOLIST macro. Every link consists of several

fields

148

.

List of links pointing to all events in current member. It can be used only w ithin DOLIST macro. Every link consists of several

fields

148

.

List of links pointing to all namespaces. It can be used only w ithin DOLIST macro. Every link consists of several

fields

148 .

List of links pointing to all structures in current member. It can be used only w ithin DOLIST macro. Every link consists of several

fields

148

.

List of links pointing to all interfaces in current member. It can be used only w ithin DOLIST macro. Every link consists of several

fields

148

.

List of links pointing to all delegates in current member. It can be used only w ithin DOLIST macro. Every link consists of several

fields

148

.

List of links pointing to all enumerations in current member. It can be used only w ithin DOLIST macro. Every link consists of several

fields

148

.

List of links pointing to all forms in current member. It can be used only w ithin DOLIST macro. Every link consists of several

fields

148

. It is alw ays empty if List form s under separate category is unchecked in

compile options

48 .

List of links pointing to all classes in current member. It can be used only w ithin DOLIST macro. Every link consists of several

fields

148

. This list doesn't contain forms if List form s under separate category is checked in

compile options

48 .

List of links pointing to all modules in current member. It can be used only w ithin DOLIST macro. Every link consists of several

fields

148

.

List of links pointing to all variables in current member. It can be used only w ithin DOLIST macro. Every link consists of several

fields

148 .

List of links pointing to all constants in current member. It can be used only w ithin DOLIST macro. Every link consists of several

fields

148

.

List of links pointing to all superclasses of current member. It can be used only w ithin DOLIST macro. Every link consists of several

fields

148

.

The classes are not alphabetically sorted. They are ordered according to inheritance relation.

List of links pointing to all direct subclasses of current member. It can be used only w ithin DOLIST macro. Every link consists of several

fields

148

.

List of links pointing to all overloaded members of current member including current member. It can be used only w ithin DOLIST macro.

Every link consists of several

fields

148 .

List of Applies To links. It can be used only w ithin DOLIST macro. Every link consists of several

fields

148

.

List of links pointing to all entries in index. It can be used only w ithin

DOLIST macro. Every link consists of several

fields

148 .

List of links pointing to all custom subtopics in current topic. It can be used only w ithin DOLIST macro. Every link consists of several

fields

148 .

List of type parameters descriptions for generics. It can be used only w ithin DOLIST macro. Every list item consists of several

fields

148

.

List of parameters descriptions. It can be used only w ithin DOLIST macro. Every list item consists of several

fields

148

.

List of exceptions descriptions. It can be used only w ithin DOLIST macro.

Every list item consists of several

fields

148 .

List of first parameter settings descriptions. It can be used only w ithin

DOLIST macro. Every list item consists of several

fields

148

.

© 2017 Helixoft

$SET02-LIST$

$SET03-LIST$

$MEMBER-NAME$

$MEMBER-PURE-NAME$

$MEMBER-FULLNAME$

$MEMBER-NAME-NOPARAMS$

$MEMBER-NAMESPACE$

$MEMBER-ASSEMBLY-NAME$

$MEMBER-ASSEMBLY-VERSION$

$MEMBER-LINK$

$MEMBER-TYPE$

$MEMBER-EXAMPLE$

$MEMBER-PARENT$

$MEMBER-DESCRIPTION$

$MEMBER-REMARKS$

$MEMBER-RETURN$

$MEMBER-AUTHOR$

$MEMBER-REVISION$

$MEMBER-VERSION$

$USER-TAGS-LIST$

$MEMBER-NEEDS-PARENT$

$MEMBER-SOURCECODE$

$MEMBER-DECLARATION$

$MEMBER-CSHARP-DECLARATION$

$MEMBER-CPP-DECLARATION$

$MEMBER-CPP2-DECLARATION$

$MEMBER-JSCRIPT-DECLARATION$

$MEMBER-ACCESS$

$MEMBER-PUBLIC$

$MEMBER-PRIVATE$

$MEMBER-FRIEND$

$MEMBER-PROTECTED$

$MEMBER-PROTECTED-FRIEND$

© 2017 Helixoft

VSdocman Templates 147

List of second parameter settings descriptions. It can be used only w ithin DOLIST macro. Every list item consists of several

fields

148

.

List of third parameter settings descriptions. It can be used only w ithin

DOLIST macro. Every list item consists of several

fields

148

.

Name of currently processed member (including parameters if any).

Name of currently processed member (w ithout parameters if any).

Full name of currently processed member (including parameters if any).

Name of currently processed member w ithout parameters.

Namespace of currently processed member.

Assembly name of currently processed member.

Assembly version of currently processed member.

Link of of currently processed member.

Type of currently processed member, e.g. class, method, ...

Example for currently processed member.

Parent name of currently processed member.

Description of currently processed member.

Remarks of currently processed member.

Returns field of currently processed member.

Author of currently processed member.

Revision date of currently processed member.

Version of currently processed member.

A list of user-defined tags and their values for current member. The list

has the same number of items as number of user tags defined in options

74 . The $LIST-ITEM-LABEL$ field is used for user section heading and $LIST-ITEM-COMMENT$ stores its contents. If the user tag is not used in current member, the $LIST-ITEM-COMMENT$ field is empty.

Flag indicating w hether member needs also parent name to fully identify.

If so, its value is "1", empty string otherw ise. It is used to distinguish e.g.

tw o various variables of various classes w ith the same name: variable

(Class1) and variable (Class2).

Source code of currently processed member. New lines are separated

by $EOL$

31 macro. Some processing tools may report w arnings because source code can contain statements like this: "If a<> 0 Then", w hich can be interpreted as empty tag in markup languages.

Declaration of currently processed member in VB syntax.

Declaration of currently processed member in C# syntax.

Declaration of currently processed member in C++ w ith managed extensions syntax.

Declaration of currently processed member in pure C++ (.NET 2.0

version) syntax.

Declaration of currently processed member in JScript syntax.

Accessibility of currently processed member, e.g. Public, Private, ....

Returns "Public" if currently processed member is public, otherw ise "".

Returns "Private" if currently processed member is private, otherw ise "".

Returns "Friend" if currently processed member is friend, otherw ise "".

Returns "Protected" if currently processed member is friend, otherw ise

"".

Returns "Protected Friend" if currently processed member is friend, otherw ise "".

148 VSdocman Help

$MEMBER-OBSOLETE$

$MEMBER-FLAGS-ATTRIBUTE$

$TOPIC-FOOTER$

$GROUP-PROJECTS-LIST$

$CHRn$

$SUPPORTED-PLATFORMS$

$SUPPORTED-NET-FRAMEWORK$

$SUPPORTED-NET-CF$

$SUPPORTED-XNA-FRAMEWORK$

$COMPILING-SOLUTION-TO-SINGLE$

$MEMBER-IS-VB$

$MEMBER-IS-CSHARP$

$HELP-TITLE$

$DEFAULT-TOPIC-LINK$

$MEMBER-CREF$

$MEMBER-PARENT-CREF$

$MEMBER-IS-OPERATOR$

$MEMBER-CREF-NOPREFIX-NOPARAMS$

$MEMBER-OVERLOADS-DESCRIPTION$

$MEMBER-OVERLOADS-REMARKS$

$MEMBER-OVERLOADS-EXAMPLE$

Fields in lists

Returns value of Obsolete attribute of the member or empty string if

Obsolete attribute is not defined.

Returns non-emty string if Flags attribute is specified on enumeration.

Topic footer text.

List of project names in the project group.

Expands to ASCII character specified by n. Allow s to add any character

(w ith ASCII code 0-255) into resulting documentation. For example

$CHR13$$CHR10$ inserts a new line.

Text show n in Platforms section.

Comma delimited supported .NET Framew ork versions.

Comma delimited supported .NET Compact Framew ork versions.

Comma delimited supported XNA Framew ork versions.

Returns non-empty string if w e are compiling solution to single documentation.

Returns "VB .NET" if member is w ritten in VB, empty string otherw ise.

Returns "C#" if member is w ritten in C#, empty string otherw ise.

The documentation title defined in

output options

55 .

A link to the default topic.

A cref value of link of currently processed member.

A cref value of link of currently processed member's parent.

Returns non-empty string if member is operator, empty string otherw ise.

A cref value of link of currently processed member but w ithout prefix and parameters.

Overloads summary of currently processed member.

Overloads remarks of currently processed member.

Overloads example of currently processed member.

Every item in every list contains a set of fields. The field is also the macro. Some of them have not meaning w ith all the lists.

The fields that have meaning w ith all lists:

Macro

$LIST-ITEM-NUMBER$

$LIST-ITEM-LABEL$

$LIST-ITEM-FIRST$

$LIST-ITEM-LAST$

$LIST-ITEM-COMMENT$

$LIST-ITEM-TYPE$

$LIST-ITEM-SUMMARY$

$LIST-ITEM-OVERLOADS-SUMMARY$

Meaning

Order number of current item in list.

Textual label of current item in list.

A flag, empty if it is not first item in the list, otherw ise "1".

A flag, empty if it is not last item in the list, otherw ise "1".

Usually comment about inherited item. Also used for contents of user tags.

Usually item type e.g. Class, Method, ...

Summary of target member.

Overloads summary of target member.

The fields that have meaning only w ith lists containing some links:

Macro Meaning

© 2017 Helixoft

VSdocman Templates 149

$LIST-ITEM$

$LIST-ITEM-FULLNAME$

$LIST-ITEM-LOCATION$

$LIST-ITEM-FILE$

$LIST-ITEM-CREF$

$LIST-ITEM-HELPID$

$LIST-ITEM-OBSOLETE$

$LIST-ITEM-MSDN-A-KEYWORD$

$LIST-ITEM-MSDN-WEB-FILENAME$

$LIST-ITEM-SIMPLE-VBDECLARATION$

$LIST-ITEM-SIMPLE-CSHARPDECLARATION$

$LIST-ITEM-SIMPLE-CPPDECLARATION$

$LIST-ITEM-SIMPLE-JSCRIPTDECLARATION$

$LIST-ITEM-SIMPLE-CPP2DECLARATION$

$LIST-ITEM-PUBLIC$

$LIST-ITEM-PRIVATE$

$LIST-ITEM-FRIEND$

$LIST-ITEM-PROTECTED-FRIEND$

$LIST-ITEM-PROTECTED$

$LIST-ITEM-STATIC$

$LIST-ITEM-SUPPORTS-NETCF$

$LIST-ITEM-IS-OPERATOR$

Name of referenced member.

Full name of item.

Module of referenced member.

Filename if item is file reference, empty otherw ise.

A cref value of link of referenced member.

Context help ID of referenced member.

Returns value of Obsolete attribute of referenced member or empty string if Obsolete attribute is not defined.

MSDN A-keyw ord for referenced member.

File name of the topic in w eb MSDN for referenced member.

One line Visual Basic declaration of referenced member.

Used e.g. in overloads list.

One line C# declaration of referenced member. Used e.g. in overloads list.

One line C++ w ith managed extensions declaration of referenced member. Used e.g. in overloads list.

One line JScript declaration of referenced member. Used e.g. in overloads list.

One line pure C++ (.NET 2.0 version) declaration of referenced member. Used e.g. in overloads list.

Non-empty string if referenced member is public.

Non-empty string if referenced member is private.

Non-empty string if referenced member is friend in VB

(internal in C#).

Non-empty string if referenced member is protected friend in

VB (internal protected in C#).

Non-empty string if referenced member is protected.

Non-empty string if referenced member is shared in VB

(static in C#).

Non-empty string if referenced member is supported by

.NET Compact Framew ork.

Non-empty string if referenced member is operator, empty string otherw ise.

The fields that have meaning only w ith $PARAM-LIST$, $TYPE-PARAM-LIST$, $SET01-LIST$, $SET02-LIST$ and $SET03-

LIST$ lists:

Macro

$LIST-ITEM-PARAM$

Meaning

Name of parameter.

The fields that have meaning only w ith $SET01-LIST$, $SET02-LIST$ and $SET03-LIST$ lists:

Macro

$LIST-ITEM-CONSTANT$

$LIST-ITEM-VALUE$

See Also

Meaning

Name of constant for current setting.

Value of constant for current setting.

© 2017 Helixoft

150 VSdocman Help

VSdocman macro language

144

8.3.2

Compulsory Macros

They must be defined by user because VSdocman uses their values during compilation.

Macro

$SPLIT$

$MEMBER-EXT$

Meaning

Flag indicating w hether all members have its ow n file. If set to "0", then everything w ill be in one file, if "1" then every part of documentation has its ow n file.

File extension of member file.

$INDEX-EXT$

$CONTENTS-EXT$

$PROJECT-EXT$

$vbdoc-description$

$vbdoc-constructor-body$

File extension of index file.

File extension of contents file.

File extension of documentation project file.

A description of current template w hich is show n in VSdocman dialog.

Definition of constructor documentation.

$vbdoc-m ethod-body$

$vbdoc-property-body$

$vbdoc-event-body$

$vbdoc-variable-body$

$vbdoc-constant-body$

$vbdoc-object-body$

$vbdoc-stdm odule-body$

$vbdoc-form -body$

$vbdoc-delegate-body$

$vbdoc-enum eration-body$

$vbdoc-interface-body$

$vbdoc-nam espace-body$

$vbdoc-structure-body$

$vbdoc-index-body$

$vbdoc-contents-body$

$vbdoc-project-body$

$vbdoc-group-project-body$

$vbdoc-group-contents-body$

$vbdoc-exec-after$

Definition of method documentation.

Definition of property documentation.

Definition of event documentation.

Definition of variable documentation.

Definition of constant documentation.

Definition of object (class) documentation.

Definition of module documentation.

Definition of form documentation.

Definition of delegate documentation.

Definition of enum documentation.

Definition of interface documentation.

Definition of namespace documentation.

Definition of structure documentation.

Definition of index.

Definition of contents.

Definition of documentation project.

Definition of documentation project for w hole solution.

Definition of contents for w hole solution.

MS DOS commands w hich are to be executed after compilation has been done. This is useful to define some additional operations such as files renaming, copying or executing some external application.

Name of the resulting help file.

$vbdoc-help-file$

$EOL$

31

$C$ and $END-C$

$CODE$

31 and

$END-CODE$

31

$IMG$

31 and

$GMI$

31

$REPLACE-TABLE$

End of line sequence for given documentation format.

Start and end of inline code expression for given documentation format.

Start and end of source code block for given documentation format.

Inline image.

Table of strings to be replaced. It is sequence of strings delimited by space. First string w ill be replaced by second, third by fourth and so on.

If you need to have space in some of these strings, use $CHR32$. This macro need not to be defined.

© 2017 Helixoft

$CHAR-ENCODING$

$TYPE-CLASS$

$TYPE-MODULE$

$TYPE-EVENT$

$TYPE-PROPERTY$

$TYPE-VARIABLE$

$TYPE-CONSTANT$

$TYPE-METHOD$

$TYPE-DELEGATE$

$TYPE-ENUMERATION$

$TYPE-INTERFACE$

$TYPE-STRUCTURE$

$TYPE-NAMESPACE$

$TYPE-CONSTRUCTOR$

See Also

VSdocman macro language

144

VSdocman Templates 151

All text (not defined in template file) w hich is betw een

$REPLACE-

ON$

153

and

$REPLACE-OFF$

154

macros w ill be replaced. It is useful for implementing escape characters, e.g. "&lt" for "<" in HTML templates.

Encoding used for output. Supported values are:

·

UTF-8...used in HTML and XML based output formats

·

DEFAULT...Default OS encoding. Chars are just copied w ithout modification.

Type name for Class type member. Used as a value of $LIST-ITEM-

TYPE$ macro and in the index entries. Useful for translating the templates.

Type name for Module type member. Used as a value of $LIST-ITEM-

TYPE$ macro and in the index entries. Useful for translating the templates.

Type name for Event type member. Used as a value of $LIST-ITEM-

TYPE$ macro and in the index entries. Useful for translating the templates.

Type name for Property type member. Used as a value of $LIST-ITEM-

TYPE$ macro and in the index entries. Useful for translating the templates.

Type name for Variable type member. Used as a value of $LIST-ITEM-

TYPE$ macro and in the index entries. Useful for translating the templates.

Type name for Constant type member. Used as a value of $LIST-ITEM-

TYPE$ macro and in the index entries. Useful for translating the templates.

Type name for Method type member. Used as a value of $LIST-ITEM-

TYPE$ macro and in the index entries. Useful for translating the templates.

Type name for Delegate type member. Used as a value of $LIST-ITEM-

TYPE$ macro and in the index entries. Useful for translating the templates.

Type name for Enumeration type member. Used as a value of $LIST-

ITEM-TYPE$ macro and in the index entries. Useful for translating the templates.

Type name for Interface type member. Used as a value of $LIST-ITEM-

TYPE$ macro and in the index entries. Useful for translating the templates.

Type name for Structure type member. Used as a value of $LIST-ITEM-

TYPE$ macro and in the index entries. Useful for translating the templates.

Type name for Namespace type member. Used as a value of $LIST-ITEM-

TYPE$ macro and in the index entries. Useful for translating the templates.

Type name for Constructor type member. Used as a value of $LIST-ITEM-

TYPE$ macro and in the index entries. Useful for translating the templates.

© 2017 Helixoft

152 VSdocman Help

8.3.3

Command Macros

Commands are macros that are used to make loops and conditions or other operation. Only 8 commands are implemented:

1.

$DOLIST$

152

2.

$IFNOTEMPTY$

152

3.

$RESET-COUNTER$

153

4.

$INC-COUNTER$

153

5.

$DEC-COUNTER$

153

6.

$REPLACE-ON$

153

7.

$REPLACE-OFF$

154

8.

$IN-NEW-FILE$

154

See Also

VSdocman macro language

144

8.3.3.1

$DOLIST$ Macro

Enumerates a list of items. It is used to make loops in generated text.

Syntax

$DOLIST$ list body

$END-DOLIST$

List is any list provided by VSdocman. See

read-only macros

145

. The body is any text that can appear inside macro body, that means also another macro call. Thus, $DOLIST$ macro may be nested.

Exam ple

$DOLIST$ $SEE-LINK-LIST$

The $LIST-ITEM-NUMBER$. item in See Also list is $LIST-ITEM-LABEL$.

$END-DOLIST$

If $SEE-LINK-LIST$ contains 13 items, then 13 sentences are generated:

The 1. item in See Also ...

The 2. item in See Also ...

...

The 13. item in See Also ...

See Also

VSdocman macro commands

152

8.3.3.2

$IFNOTEMPTY$ Macro

Evaluates an expression and conditionally generates the text.

Syntax

$IFNOTEMPTY$ object

[then-body]

© 2017 Helixoft

VSdocman Templates 153

[$ELSEIF$]

[else-body]

$END-IFNOTEMPTY$

Object is any macro name. If expansion of object returns non-empty string or a list, then then-body is returned as the expansion of $IFNOTEMPTY$ macro. Otherw ise the else-body is returned if any.

The then-body and else-body is any text that can appear inside macro body, w hich means also another macro call. Thus,

$IFNOTEMPTY$ macro may be nested.

Exam ple

$IFNOTEMPTY$ $OVERLOAD-LINK-LIST$

Url = "$LIST-ITEM-LOCATION$_overloads+$MEMBER-EXT$"

$ELSEIF$

Url = "$vbdoc-filename$"

$END-IFNOTEMPTY$

See Also

Read-only macros

145

|

VSdocman macro commands

152

8.3.3.3

$RESET-COUNTER$ Macro

Sets internal counter $COUNTER$ to 1.

Syntax

$RESET-COUNTER$

See Also

VSdocman macro commands

152

8.3.3.4

$INC-COUNTER$ Macro

Increments the value of internal counter $COUNTER$ by 1.

Syntax

$INC-COUNTER$

See Also

VSdocman macro commands

152

8.3.3.5

$DEC-COUNTER$ Macro

Decrements the value of internal counter $COUNTER$ by 1.

Syntax:

$DEC-COUNTER$

See Also

VSdocman macro commands

152

8.3.3.6

$REPLACE-ON$ Macro

Tells the compiler to start replace the strings using

$REPLACE-TABLE$

150 . Only texts provided by compiler (e.g. source code, description, ...) are processed. That means that all text defined in template files w ill remain unchanged.

Syntax

$REPLACE-ON$

© 2017 Helixoft

154 VSdocman Help

See Also

VSdocman macro commands

152

8.3.3.7

$REPLACE-OFF$ Macro

Tells the compiler to stop replace the strings using

$REPLACE-TABLE$

150

. Only texts provided by compiler (e.g. source code, description, ...) are processed. That means that all text defined in template files w ill remain unchanged.

Syntax

$REPLACE-OFF$

See Also

VSdocman macro commands

152

8.3.3.8

$IN-NEW-FILE$ Macro

Instructs the VSdocman to close the file that is currently w ritten to and to start w riting output into a new file. If the new file exists, it is overw ritten. All output is w ritten to its default files but w ith this macro you can create additional files.

Syntax:

$IN-NEW-FILE$ path

The path is the full path to the new file.

See Also

VSdocman macro commands

152

9 Troubleshooting

9.1

"Action canceled" message in CHM

Problem

When you open CHM from netw ork location and try to open any topic, you get "Action canceled" error page.

Explanation

The HTML Help view er has canceled the display of the help file due to security restrictions. This w ill happen w ith all HTML

Help files that you open over a netw ork connection (note, that local HTML Help files w ill not be affected). This behavior is caused by Window s security update 896358, see http://support.microsoft.com/kb/896358 for more details.

Solutions

·

Place the CHM documentation on local drive.

·

Use some w orkarounds mentioned at http://support.microsoft.com/kb/896358 .

·

Use free utility HHReg w hich fixes this new limitation by explicitly registering the help file in the Window s registry. You can get it from http://w w w .ec-softw are.com/products_hhreg.html

. You can call Hhreg.exe directly from the template to register

CHM on your computer. Open your CHM template in text editor and find a line containing call to hhc.exe in $vbdoc-execafter$ macro. It ends like: hhc.exe" "$OUTPUT-PATH$\$PROJECT-NAME$$PROJECT-EXT$"

Add call to Hhreg.exe somew here after it. If you have installed Hhreg.exe to c:\myfolder then it should be as follow s:

@"c:\myfolder\hhreg.exe" /s "$OUTPUT-PATH$\$PROJECT-NAME$.chm"

© 2017 Helixoft

Troubleshooting 155

See Also

Compiling options dialog

48

9.2

Warning: The dead link ...

Problem

When compiling a documentation, the follow ing messages appear in the progress dialog:

Warning: The dead link 'LLL' was found in 'MMM' member.

The documentation is generated.

Explanation

This is not a fatal error. It appears every time the link is to be created to the target w hich does not exist in the resulting documentation. In this case, only text w hich is not a link is created.

There are several reasons w hy the target does not exist:

1.

The link in the VSdocman comment in relevant tags (

<seealso>

116

,

<see>

119

, ...) is misspelled.

2.

The link is correct but the target is not included in the documentation because: o The target is not commented w ith

VSdocman comments

19 and the

Com pile also non-com m ented m em bers

48 option is unchecked.

o The target type is unchecked in the

Compiling options dialog

48 . Remember that if the type is excluded (e.g. a class), its members (methods, properties) are automatically excluded as w ell, even w hen they are nor explicitly unchecked in the options.

o The target is located in the file w hich is not selected in the File Compiling Options dialog.

o The target is excluded by a regex filter.

o The target is excluded by conditional compilation w ith

<compilew hen>

127 tag.

There are tw o reasons w hy the link is created:

1.

It is explicitly defined in VSdocman comment by user using the relevant tags (<see>, <seealso>, ...)

2.

It is created automatically. For example w hen VSdocman compiles some class, it automatically creates Methods list of the methods of this class. As described in point 2. above, there is a possibility that some method is not included in documentation. This is the m ost com m on reason for the w arning.

3.

It is used in a class diagram.

Solutions

·

Make sure that all explicit links in VSdocman comments are spelled correctly.

·

Make sure that all targets of all links are included in the documentation: o Check

Com pile also non-com m ented m em bers

48 option in Compiling options dialog w hen the target is not commented w ith VSdocman comments or comment the target w ith VSdocman comments.

o Check the type of the target in the options.

o Select the file of the target in the options.

·

Remember that all methods and properties are also potential targets of automatic Mem bers links in their classes.

Therefore, the previous point also applies to them.

See Also

© 2017 Helixoft

156 VSdocman Help

Troubleshooting: Topics Not Created

156

9.3

Topics Not Created

Problem

There is no topic generated or only some topics are created in resulting documentation, w hen compiling project.

Explanation

VSdocman can create topics for all supported members in a source code (classes, properties, methods, events, ...). User can define w hich of them are to be included and w hich not, using

Compiling options dialog

48 .

Only members commented w ith

XML comments

19 are included, if Com pile also non-com m ented m em bers check box is unchecked. Therefore, trying VSdocman w ith your project w hich is not commented w ith XML comment results in documentation w ith no topics.

In addition, only those types of members appear in documentation w hich are checked in the options.

Moreover, as the last filter, only those files from your project are processed w hich are checked in the options dialog.

Solutions

·

Check Com pile also non-com m ented m em bers

48 option in Compiling options dialog w hen you w ant to include all selected members. All members commented w ith VSdocman comments w ill use them in the documentation. For all other members there w ill be a default temporary documentation automatically generated and used. This documentation w ill not be w ritten in the source code.

·

All types of members that you w ant to appear in documentation should be checked in the options.

See Also

Compiling options dialog

48

9.4

Links in Docx don't Work

Problem

In generated docx, the links that point to topics inside the document don't w ork. When you click the link, you'll be redirected to the start of the document.

Explanation

VSdocman assigns a bookmark to each topic. A link to a topic is then created as a cross-reference to such a bookmark. A bookmark name is generated from a member name using

File Names

65 settings. If you use default Num eric file nam es, the bookmark name w ill have a short numeric form. You can see it w hen you hover over the link.

If you, how ever, use Pretty file nam es, the bookmark name w ill be constructed from code member's full name and this can lead to a quite long bookmark name.

© 2017 Helixoft

Troubleshooting 157

But MS Word has a limit of 40 characters for bookmark names. If you exceed that limit, you'll get the behavior described above.

Solution

·

Alw ays use Num eric file nam es w hen you generate docx format.

See Also

File Names options

65

9.5

HHC5010: Error

Problem

When you generate HTML Help 1.x documentation, you get the follow ing error:

HHC5010: Error: Cannot open "output_path\project_name.chm". Compilation stopped.

Explanation

There are tw o possible reassons.

1.

CHM file is already open or used. This happens if you open CHM and then try to recompile it.

2.

HTML Help 1.x command line compiler hhc.exe cannot compile CHM file to folder w hose full path contains folder name starting w ith dot. If you have that problem, you probably specified output path w ith folder starting w ith dot, e.g. "d:\My files\.NET\documentation". You can use dots in folder names but not at the beginning.

Solution

·

Close CHM file or applications that use it.

·

Specify output path w ithout folders starting w ith dot. Generated CHM file can be placed to such folder later

See Also

View HTML Help 1.x Documentation

88 |

Output Options

55

10 About

C opyright © 2003-2017 He lixoft

Home page and re gistration info: http://www.helixoft.com/

E-mail: [email protected]

How to register

© 2017 Helixoft

158 VSdocman Help

Anyone may use this softw are during a trial period of 14 days. Follow ing this trial period of 14 days or less, if you w ish to continue to use VSdocman, you MUST register (buy). When you buy VSdocman, you become registered user.

Please visit http://w w w .helixoft.com/buy.htm

.

© 2017 Helixoft

Index

- $ -

$DEC-COUNTER$ 153

$DOLIST$ 152

$IFNOTEMPTY$ 152

$INC-COUNTER$ 153

$IN-NEW-FILE$ 154

$REPLACE-OFF$ 154

$REPLACE-ON$ 153

$RESET-COUNTER$ 153

- < -

<author> 130

<b> 124

<br> 125

<c> 121

<code> 120

<compilewhen> 127

<example> 113

<exception> 115

<font> 123

<i> 124

<img> 123

<include> 126

<includesource> 129

<list> 122

<overloads> 117

<para> 119

<param> 114

<paramref> 116

<permission> 127

<remarks> 112

<returns> 112

<revision> 130

<see> 119

<seealso> 116

<summary> 111

<threadsafety> 128

<typeparam> 114

<typeparamref> 118

<u> 125

<userN> 130

© 2017 Helixoft

Index 159

<value> 113

<version> 129

- A -

Action canceled 154

additional topics 58

attached property 28

author name 130

- B -

bold 124

- C -

class diagram 32, 123

code 31, 120, 121

command line 25

Comment editor 142

editing advanced fields 134

editing examples 139

editing links 137

editing misc fields 140

editing parameters 136

editing summary and remarks 135

editing user fields 141

general options 83

modal 81 modeless 81

overview 131

viewing XML comment 142

window options 81

WYSIWYG 133

Comment Editor Options - Window 81

comment template 76, 78, 80

comments

adding 19

editing 131

syntax 22

tags 110

templates 75

user tags 74

xml comments 22

common 45

compiling 14

conditional compilation 127

160 VSdocman Help

Conditional Compilation Options 53

conflict 97

Context help 25

Context Help Options 67

cref 116, 119

custom topics 24, 58

- D -

dependency property 28

Deploy

chm 90

context help 104

html 87

hxs 101

MS Help Viewer 90, 92 mshc 90, 92

solution 104

tool 106, 107

diagram 32, 123

docx 156

- E -

enumerations 63

Environment Options 84

external comments 126

external files 27

- F -

F1 25, 102

Files Compile Options 49

filter

accessibility 48

file 49

member type 48

regex 50

font color 123

footer 64

formatting text 30

friend 48

- G -

General Comment Editor Options 83

General Comment Options 72

- H -

Helixoft 157

HelixoftHelpReg.exe 106

HelpLibManagerLauncher.exe 107

HHC5010 157

HxComp.exe 84

- I -

images 31, 123

include 126

including source code 129

inline code 121

internal 48

italics 124

- K -

keyboard shortcuts 87

keyword 119

- L -

langword 119

line break 125

links 116, 119

links don't work 156

lists 122

localization 34

- M -

macros

commands 152

compulsory macros 150

read-only macros 145

syntax 144

using in text 33

Members Compile Options 48

MS Help Viewer 97 mshc 97

© 2017 Helixoft

- N -

namespace 35

new line 31

newline 125

- O -

Options 71

Output format 57

Output Options - File Names 65

Output Options - General 55

- P -

Page Setup Options 64

paragraph 31, 119

permissions 127

pictures 31, 123

Platforms & Frameworks Options 62

private 48

Profiles 40

project 36

properties 36, 45

protected 48 public 48

- R -

regex 50, 78 regular expression 78

revisions 130

Root Namespace Options 69

rule 76, 78

- S -

security 127

See also 35

shortcuts 87

solution

compile 17

deploy 104

solution-wide 45

sort 35

© 2017 Helixoft

Index 161

source code 31, 120

Syntax & Source Code Options 61

- T -

tables 32, 122

tags 110

Templates

comment template 75, 76, 78, 80

edit 143

output template 142, 144 syntax 144

vbdt file 143

The dead link ... 155

threads 128

Title page text 64

topic 97

topics not created 156

troubles 154, 155, 156, 157

- U -

underlined 125

updates 85

user defined comment tags 130

User Tags Options 74

user-defined topics 58

- V -

VBdocman_ListNamespacesWithShortNames 35

version 97

versions 129

Viewing

chm 88 chw 88

context help 102

HTML 87

hxs 98

MS Help Viewer 90, 91 mshc 90, 91

solution 104

vsdoc 71

VSdocman 7

main window 11

162 VSdocman Help

- X -

XML comments 22

XML tags 110

© 2017 Helixoft

advertisement

Was this manual useful for you? Yes No
Thank you for your participation!

* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project

Related manuals

Download PDF

advertisement

Table of contents