VSdocman 3.5 - Code Commenter and Generator of Class Documentation for VB .NET and C#


1. OVERVIEW

VSdocman is a tool for commenting and the quick automatic generation of class documentation from your C# and VB .NET source code files. It is ideal tool for you if you create .NET component, control, application, smart device or web site (ASP .NET) projects.

VSdocman parses the Visual Basic .NET and C# projects and automatically creates MSDN-like API documentation with the table of contents, index, topics, cross-references, IntelliSense and F1 context sensitive help. 

With VSdocman you can:
 - Add and use XML comments in your source code.
 - Take advantage of its sophisticated WYSIWYG comment editor which helps you write your XML comments.
 - Easily insert tables, lists, pictures, links and other formatting directly in your source code.
 - Generate professional documentation in multiple and localizable output formats - HTML, CHM, Help2, RTF, XML (including new MSDN2 look).
 - Fully integrate generated help into VS help system.
 - Generate documentation in command line mode.
 - Easily deploy Help2 documentation to the target computers.

VSdocman works as an add-in with:
 - Visual Studio 2008 - all editions except for Express edition
 - Visual Studio 2005 - all editions except for Express edition
 - Visual Studio .NET 2003
 - Visual Studio .NET 2002



2. BENEFITS

 - You will get your API reference with just single mouse click. In large projects, VSdocman will save many days of boring tedious work. 
 - All in one . You can create complex comments, generate documentation and then deploy and register it.
 - Professional documentation of your components can be created in seconds for your customers or co-developers.
 - Consistency. All changes in the code are automatically reflected in newly generated documentation.
 - Documentation in various formats can be generated with a few mouse clicks and you have documentation in all supported formats in a few minutes.
 - Efficient communication within the team, especially when version control (e.g. SourceSafe) is used. Every programmer comments his part of the code. Everybody in the team can then make documentation and easily understand that code and get on-line help.
 - The source code is precisely commented and looks nice.



3. INSTALLATION

Before installing VSdocman uninstall any previous versions of VSdocman installed on your computer. Then just unzip installation package and run installation MSI file. VSdocman will be installed. After that it should be accessible in Visual Studio .NET IDE Add-Ins list. Detailed help is also available.



4. UNINSTALLATION

Go to "Control Panel" -> "Add/Remove Programs" and select VSdocman. All work is done automatically.



5. TRIAL VERSION

Trial 14 day version of VSdocman comes with these limitations:
 - warning message is displayed every time a new documentation is compiled
 - you are not allowed distribute generated Help 2 and HTML Help 1.x documentation with included HelixoftHelpReg.exe tool which automatically registers the documentation with Visual Studio .NET help




6. HOW TO REGISTER

Anyone may use this software during a trial period of 14 days.
Following this trial period of 14 days or less, if you wish to continue
to use VSdocman, you MUST register (buy). When you buy VSdocman, you become
registered user.

Registered users will get:
 - full product license
 - free email support for the period of two years
 - free minor version upgrades at any time
 - free major version upgrades within 90 days of any registered purchase
 - discounts on non-free upgrade

You can register at http://www.helixoft.com via secure connection using ShareIt! service.
ShareIt! is well-known, leading shareware registration company.
It is quick and easy. Usually, you will have the full version in a while.

We accept Mastercard/Eurocard, Visa, American Express, and Diner's Club online.
Alternatively, we support bank transfer/wire transfer, we accept Checks and Money Orders
through postal mail. Corporate users may place purchase order.

Immediately after the payment is accepted you receive e-mail with registration code. Download and install the trial version of VSdocman. Go to VSdocman main dialog and press REGISTER button to enter the code. If the code is valid, trial version becomes a full version immediately.

Please visit http://www.helixoft.com/buy.htm.



7. CHANGES

In version 3.5
 1. NEW: Enum items can be sorted by name, value or unsorted. (No GUI option yet. You need to manually edit .vsdoc file.)
 2. CHANGE: The comment editor generates the top level XML comment tags - <summary>, <remarks>, <returns>, <value> and <example> on separate lines instead of on one line.
 3. CHANGE: When reading top level XML comment tags (e.g. <summary> or <remarks>), all leading and trailing whitespaces in tag value are ignored now.
 4. CHANGE: Member chapters in RTF output have different styles now (Heading 1-4). This allows better customization, e.g. numbering, custom structured TOC, etc.
 5. FIX: VSdocman wasn't present in VS 2008 sometimes if both VS 2005 and VS 2008 were installed.
 6. FIX: The help2_msdn2 output works with both VS 2005 and VS 2008 MSDN now.
 7. FIX: When generating documentation using "Compile Solution to Single Documentation", some projects didn't appear in the table of contents. They were only visible in Index.
 8. FIX: In Web Site projects (not Web Application projects), there was no syntax section generated for methods.
 9. FIX: In Web Site projects (not Web Application projects), compilation was aborted with "Unspecified error" if project contained overloaded methods.
10. FIX: In Web Site projects (not Web Application projects), also aspx files appeared randomly in the files list in Compile - Files options.
11. FIX: Sometimes, "Error reading file." error occurred in command line compilation and compilation didn't finish.
12. FIX: In VB 2005, not all overloaded properties were included in documentation. 
13. FIX: Comment editor inserted <returns> instead of <value> tag for properties.
14. FIX: Pictures included with <img> tag were not visible in RTF output.
15. FIX: The WYSIWYG comment editor appended random character to each picture, if that picture was followed by character other than white-space.
16. FIX: Occasional crash during compilation, especially with large solutions.

In version 3.4.2970
 1. NEW: The "Select link" dialog in comment editor allows selecting the members in referenced libraries (e.g. .NET classes) also in VS .NET 2002 and 2003. 
 2. CHANGE: The "ParamArray, comma-delimited list of values." text is no longer automatically prepended to description of parameters defined with ParamArray in VB or params in C#.  
 3. CHANGE: The "Optional", "Required" and "The default value is " texts are automatically prepended to optional parameter description only when parameter description is empty. (VB only). 
 4. CHANGE: The links to referenced members that are not part of .NET framework (e.g. third-party controls) are correctly generated too. There's a chance that the target help topic will be found.
 5. FIX: Inserting images in comment editor didn't work on Windows Vista.
 6. FIX: Sometimes, the command line build exited with error code 3 without generating documentation.  
 7. FIX: Comment editor generates correct cref link for generic constructed types and for arguments whose types are type parameters. The same applies to generated XML doc file. For example a method with full name
    Class1<T1, T2>.Method1<T3>(List<int> x, T2 y, T3 z) in C# or
    Class1(Of T1, T2).Method1(Of T3)(ByVal x As List(Of Integer), ByVal y As T2, ByVal z As T3) in VB
    should have the following cref link:
    M:Class1`2.Method1`1(System.Collections.Generic.List{System.Int32},`1,``0). 
 8. FIX: Methods in C# with no comment didn't inherit comment from overridden method. 
 9. FIX: The member's parent class name was not listed in See Also section of documentation generated with VS .NET 2002/2003. 
10. FIX: Wrong resizing of compilation progress dialog. 

In version 3.4.2942
 1. CHANGE: In Compile - Files options, the files are now shown as a tree for better navigation.You can easily select/deselect  whole folder now.
 2. FIX: New solution or project profile couldn't be created. This problem appeared only in version 3.4.
 3. FIX: Wrong indexing of the title page for full-text search in HTML output format.

In version 3.4
 1. NEW: Visual Studio 2008 support. 
 2. NEW: Added full-text search functionality in HTML output.  Moreover, table of contents and index are no longer implemented as Java applets. Everything is implemented in HTML and JavaScript.  This resolves security problems on intranets, various Java related issues and better indexing by search engines. 
 3. NEW: The "Select link" dialog in comment editor allows selecting also the members in referenced libraries (e.g. .NET classes) in VS 2005 and higher.
 4. CHANGE: Compiling  web site and web application projects is faster. 
 5. CHANGE: The compilation window is more responsive. You can cancel  the compilation immediately at any time. 
 6. CHANGE: The "Optional", "Required" and "The default value is " texts are automatically prepended to parameter description only when there is at least one optional parameter (it happens in VB only). Moreover, these texts are localized now. 
 7. CHANGE: Removed "Members" sub-page under namespaces in TOC. This page is not needed because all namespace members are listed on namespace main page. 
 8. CHANGE: Empty namespaces are not included in documentation. 
 9. FIX: Passing "/vs 2005" parameter to VSdocmanCmdLine.exe caused an error message. 
10. FIX: Using "/compileProject" operation in VSdocmanCmdLine.exe sometimes processed random project from the solution instead of specified project. 
11. FIX: The Help2 documentation was not registered correctly on some computers. There was no table of contents shown for generated documentation, only Index and Search worked fine. 
12. FIX: Small problems in WYSIWYG comment editor - multiple lines with formatting (e.g. bold) inside <code> tags were joined together when opened in editor again, incorrect selecting/unselecting text with Shift + down arrow, improved undo operation. 
13. FIX: When declaring some member as generic type with particular type argument, the declaration in the help didn't contain two links - one to generic type and one to type argument. For example "public ICollection<MyClass> test;" in C# or "Public test as  ICollection(Of MyClass)" in VB should contain links to ICollection and to MyClass. 
14. FIX: Complex constant and enum values in C# (hex, containing +-/* or comment) are now calculated and correctly shown in all language syntax sections. 
15. FIX: Wrong syntax was generated for classes that inherited from generic classes in C#, e.g. public class MyClass : List<int>. 
16. FIX: Wrong syntax was generated for properties with different accessibilities for getter and setter part (.NET 2.0 and higher). 
17. FIX: Compiling large web site or web application projects (more than 1000 code files) caused VS crash. 

In version 3.3
 1. NEW: Added profiles. You can now save your settings undercustom profiles and easily generatedifferent documentation for the same project. You can also exclude specific projects when compiling documentation for whole solution. 
 2. NEW: Added pt-Pt (Portuguese) output localization. 
 3. CHANGE: Enhanced command line functionality. The VS IDE is no longer shown, the messages are written directly to console standard output and added support for profiles. 
 4. CHANGE: Removed Save/Load default settings functionality. 
 5. CHANGE: Modified help2_msdn2, html_msdn2, chm_msdn2 and rtf outputs. When compiling the solution to single documentation, the help title, header and file names are based on solution name and not on the current project name. Moreover, the Help2 output no longer contains unnecessary extra root node. 
 6. CHANGE: Launching of VSdocman on web projects in VS 2005 works much faster now. 
 7. FIX: When "Public" was not selected for compilation in VSdocman options, explicitly defined namespaces and their contents were not included in documentation. 
 8. FIX: In web site projects in VS 2005, the source files in subfolders were ignored. 
 9. FIX: In Web Application projects in VS 2005 (not web sites), the code behind files of the forms were ignored. 
10. FIX: If the solution contained SQL Server 2000 Reporting Services project, the "Compile Solution" and "Compile Solution to One Documentation " buttons were not available. 
11. FIX: When Pretty file nameswere selected in Output - File Names options, constructors were not listed in documentation. 
12. FIX: The C# source code is no longer marked as Visual Basic in some output formats. The language of the source code is shown correctly for VB .NET and C#. 
13. FIX: The blank linesin source code and code examples were removed in HTML based documentation. 
14. FIX: The user defined Platforms text was ignored in some output formats. 
15. FIX: The "Copy Code" button above the code section is fixed in chm_msdn2 and html_msdn2 output. 
16. FIX: The inheritance tree was not shown for some classes and some links to framework classes didn't work as well. 
17. FIX: The class declaration was handled incorrectly if it contained conditional compilation directives (e.g. #if). 
18. FIX: Sometimes the comment editor (when set as modal) was hidden behind VS window. 
19. FIX: In comment editor, whenthe last text in table cell was code or link, the XML comment for the table was generated incorrectly.
20. FIX: Installation error on Windows Vista.

In version 3.2
 1. NEW: You can select for which languages VSdocman generates syntax - VB .NET, C#, C++ and JScript. 
 2. NEW: You can define platforms and supported frameworks.
 3. NEW: User is warned if he tries to insert picture from outside of external files folder or if external files folder is not defined.
 4. CHANGE: Adding or editing XML comments in large files works faster now. 
 5. CHANGE: Main VSdocman window stays open for further work after compiling documentation. 
 6. CHANGE: Improved RTF output. Added page numbers in TOC and index. Removed duplicate namespaces when compiling solution to single documentation. 
 7. CHANGE: Generated help page for the namespace doesn't contain declaration section anymore. 
 8. FIX: Sometimes the "Select reference" dialog didn't show all namespaces in the project. 
 9. FIX: When using help2_msdn2 output format, the topics were shown incorrectly if MSDN for VS2005 was uninstalled (replaced by full MSDN). 
10. FIX: VSdocman locked if there were /* ... */ comments inside attribute. 
11. FIX: In VS 2005, when documenting whole solution, the projects in solution folders were not included. 
12. FIX: In some rare cases, the "Dead link..." warnings appeared when there were no dead links at all. 
13. FIX: No "S" icon in class list and no "static" keyword in C# declaration for C# static classes in VS 2005. 
14. FIX: There was no link to parent class in See Also section of class members if the class was generic and written in C#. 
15. FIX: Wrong syntax of array parameters in C# methods was used in VB .NET declaration. The [] was used instead of ().
16. FIX: Namespaces were sometimes listed with full name and sometimes with short name. They are always listed with full name now.

In version 3.1
 1. Comment editor doesn't make word wrapping of the text inside <code> and <c> tags when writing comments back to source code. 
 2. Warning is shown when VSdocman cannot save its settings due to insufficient write permissions or file is read-only (because it is checked-in to SourceSafe). 
 3. FIX: Problems with generating the output for C# projects with generic members. The < and > characters in member name caused problems in HTML or XML based output formats. 
 4. FIX: Pasting of formatted text didn't work in WYSIWYG comment editor in VS 2005. 
 5. FIX: In some special cases, the XML comment was placed at incorrect place in C# source code in VS 2005. 
 6. FIX: Wrong section name for method return value in RTF output. 

In version 3.0 (VBdocman .NET renamed to VSdocman)
 1. Added full C# support. The program now supports VB .NET and C#. That's why it is renamed from VBdocman .NET to VSdocman. 
 2. Localized output in several languages including English, German, French, Spanish and Slovak. Adding new language is just matter of editing one text file. 
 3. All links (<see>, <seealso>, inheritance tree, types in declaration) can point to framework members now. 
 4. Member declaration is shown also in C#, C++ and JScript syntax and types inside are shown as links.
 5. Added ability not to list member attributes in declaration syntax section (Miscellanous - Source Code settings). 
 6. Inheritance tree shows all superclasses, even those outside the project, e.g. framework classes. 
 7. Public variables in the class are no longer listed as properties. They are listed as fields now. 
 8. Members on "Members" page are grouped and marked by accesibility (public, protected, ...). Static members have "static" icon. 
 9. Improved HTML output for even better cross-browser compatibility. 
10. Significantly improved performance speed. 
11. FIX: Comment editor was not displayed on computers with "Large Fonts" set. 
12. FIX: Problems with compilation of Declares in VS 2005. 
13. FIX: Problems with compilation of Events in VS 2005 
14. FIX: Problems in WYSIWYG comment editor: pasting multiple times, deleting text selection deleted also next character, inserting new section (e.g. Example) while text block was selected. 
15. FIX: Problems with remembering which files go to compilation. 
16. FIX: Incorrect values of enumeration constants that were not explicitly initialized. 

In version 2.3
 1. Added support for generics in VS 2005. New <typeparam> tag introduced.
 2. Improved support for partial classes and structures in VS 2005.
 3. Added support for <System.ComponentModel.Description...> attribute. You can easily insert <Description...> attribute from context menu. If you add new comment, default summary is automatically extracted from <Description...> attribute if any. 
 4. Comment editor now remembers whether it is in WYSIWYG mode and its size and position. 
 5. Removed editing of parameter settings from comment editor because parameter settings represent old practice from VB6 and you should use enumerations instead. VBdocman however still recognizes <set> and @set tags in the comments. 
 6. FIX: <returns> tag is not added by "Add XML Comment" for Subs. 
 7. FIX: VBdocman didn't work with Web projects in VS 2005.
 8. FIX: When using Compile Solution or Compile Solution to One Documentation, some projects may have empty documentation. 
 9. FIX: Compiling help for Smart Device projects didn't work. 
10. FIX: Command "VBdocmanNET.Connect.CompileSolutionToOne" didn't work from command line. 
11. FIX: Wrong adding and reading of comments in VS 2005 when member has attribute. 

In version 2.2
 1. Added support for VS 2005. Generics are not supported yet.
 2. Added support for smart device projects.
 3. VBdocman now produces and recognizes C# XML links in cref attributes. Type character is prefixed, e.g. M: or T:, [] are used instead of () for array parameters, @ is appended to ByRef parameters and there are no spaces between parameters. This is needed for good compatibility with VS 2005.
 4. Help 2 documentation can be viewed with full formatting immediately after generation.
 5. Context menus are only visible on VB and macro files.
 6. "Compile to One Solution" button is disabled when there's only one project in the solution.
 7. FIXED: When there was an option checked to generate IntelliSense XML file, some formatting tags (<c>, <see>, ...) in <summary> and <param> tags were ignored in resulting documentation.
 8. FIXED: Problem with the tabs (scrolling) in Comment Editor. 

In version 2.1
 1. Fixed bug that caused problems with setting a list of .vb files that are to be documented. This problem especially occured when updating your project from VBdocman .NET version 1.x to version 2.0.

In version 2.0
 1. New formatting and objects added to comments - bold, italic, underline, text color, links, bulleted or numbered lists, tables and pictures.
 2. Support for more XML documentation tags added - <list>, <para>, <see> and <value>.
 3. Comment editor is WYSIWYG. Only XML comments are generated by editor but VBdocman still recognizes also @-style comments.
 4. Comment editor can be also modeless, floating and dockable.
 5. <value> tag replaces <returns> tag in properties. <returns> tag is still valid in property.
 6. You can specify folder with your own external files now. All external files will be automatically included in documentation and you can reference them from your comments e.g. in <see> or <img> tags. 
 7. Added possibility to comment root namespace. 
 8. In addition to random numeric names, generated files can have also pretty and constant names based on member name. So you can easily reference them from outside. 
 9. You can generate ONE documentation for whole solution . Namespaces and members are merged into one TOC. 
 10. You can assign keyboard shortcuts to VBdocman actions.
 11. Preview of Help 2 documentation can be seen immediately after it is generated, without restarting VS. 
 12. VBdocman project settings are stored in separate .vbdoc file instead of .vbproj file. This avoids conflicts when using version control systems (SourceSafe) or automated builds. Old settings stored in .vbproj files are still valid if no .vbdoc file exists. 
 13. Documentation now indicates if a member has ObsoleteAttribute or FlagsAttribute applied. 
 14. Newly added project item is automatically included in VBdocman's Compile | Files list. 
 15. Undo operation after inserting comment by comment editor is improved. You don't need to perform Undo several times to get original state. 
 16. Inheriting of XML comments is fixed. 
 17. Paths (e.g. output path) may contain foreign non-English characters now. 
 18. Fixed problem with attributes in declarations on overloads list page. 
 19. Problem with saving of title text. Newlines were removed from title text after reloading VS. Fixed. 
 20. Missing spaces between words in RTF output when comment is on multiple lines. Fixed. 
 21. Fixed commenting of namespaces when one namespace was specified in multiple files. Now you only need to comment the namespace in one file. 


In version 1.3
 1. Fixed problems with links to external files. There is new prefix ^ for link to external files
    in addition to " prefix. 

In version 1.2
 1. Command line functionality added.
 2. Conditional compilation of individual members added. You can select for each member if it will be compiled.
 3. HTML output has now modern look, fixed scroll bars in table of contents and pages have MSDN style also in
    non IE browsers.
 4. References in XML comments that were broken to several lines are processed correctly now.
 5. Comment editor doesn't wrap references in @-style comments so that they be processes correctly.
 6. Fixed some problems when editing parameter settings in comment editor.
 7. Fixed parsing of constant value in @set tag if it was string with spaces.
 8. Fixed parsing of references in @-style comments if references contain spaces (functions with several
    parameters delimited with comma and space).
 9. Fixed functionality of "Find interesting links" button in comment editor in VS .NET 2003.
 10. @includesource tag always returned non empty value even if there was no value. Fixed.

In version 1.1.1495
 1. Auto-find button added to atomatically find hxcomp.exe anytime.
 2. Fixed problem when not all source files in the project were recognized. This happened when they had same names but were in different folders.

In version 1.1
 1. Non-english character sets supported.
 2. Non-english Visual Studio .NET supported.
 3. Ability to remove line continuations in source code listings in documentation.
 4. Compilation progress dialog can be resized to better reading of messages.
 5. Some macros added to templates to allow translation of templates to other languages.
 6. Some problems with unrecognized comments fixed.
 7. Behavior of Apply button in Comment Editor fixed.
 8. $CHRn$ macro processing fixed.
 9. When using XML comments, <, >, &, ' and " characters are escaped automatically in the background within $CODE$ block.
 10. Processing of names of overloaded members is not case-sensitive now.
 11. Fixed problems with enumeration constants in VS 2003.


8. CONTACT

Home page and registration information: http://www.helixoft.com

HELIXOFT
Tomasikova 14
080 01 Presov
Slovak Republic


Contact person:
Peter Macej
peter@helixoft.com