VSdocman

{multithumb caption=0}VSdocman can generate documentation even without any additional comments in the source code. All Methods, Properties, Events and other links are generated properly and parameters descriptions and other sections are also included.

However, it is good to include additional descriptions directly into the source code. It is done by adding standard XML comments which VSdocman understands in both C# and VB .NET.

Commenting is based on tags that are included in your comments.

For example

/// <summary>This is my method.</summary>
/// <remarks>This is a remarks section</remarks>
void MyMethod()

Automatic Addition of Comment

User can write all that comment manually but he is not required to do so. VSdocman can do that automatically. 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 whether ..." summary text is automatically generated for boolean properties. This is controlled by comment templates which are fully customizable by user. There are some predefined templates for the most common cases.

When user clicks right mouse button on the code window, the pop-up menu appears. Menu contains Add XML Comment, Comment Editor and Add Description Attribute items which perform the following actions:

Add XML Comment automatically adds the default XML comment to the current member. User can preset how the default comment should look like.
Comment Editor invokes the WYSIWYG Comment editor for selected member. This is useful when creating complicated documentation including cross-references, pictures, tables and others. Comment editor provides a user-friendly graphical way for editing the comments.
Add Description Attribute automatically adds the Description attribute to the current member. Short property description in Properties Window must be defined with System.ComponentModel.Description attribute.

There are three types of context-sensitive help:

Whole topic is shown when you point to some member in source code or Object Browser and press F1.
Quick summary is shown in IntelliSense and Object Browser.
Short property description is shown in Properties Window.

F1 Context help

To see Visual Studio dynamic help integration including context-sensitive help, go to the code editor and select expression with some method, property or other documented member. If you press F1, the proper topic should appear.

You can also press F1 on a member in Object Browser to invoke the help topic.

IntelliSense and Object Browser Quick Info

If you create a project with reference to your DLL and you use methods or properties from that DLL, IntelliSense in Visual Studio automatically shows their description and description of parameters as you write them. Description of a method or a property is taken from their <summary> tag in comments.

IntelliSense auto-completion

IntelliSense description

You can see the summary information in Object Browser as well.

Your API description in Object Browser

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.

Description in Properties Window

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

[System.ComponentModel.Description("Indicates button state.")]
public bool Pushed

VSdocman offers an easy way to do it through context menu.

VSdocman uses special files called templates to generate its output. A template defines a format of the output. VSdocman comes with several predefined templates for generating:

MS Help Viewer - Microsoft help technology used in Visual Studio 2010 and higher and in MSDN; .mshc file. Suitable for integration with VS help or MSDN.
MS Help 2 - Microsoft help technology used in Visual Studio .NET and MSDN versions 2002 - 2008; .HxS file. Suitable for integration with VS help or MSDN.
CHM (HTML Help 1.x) - .CHM file suitable for general purpose help.
HTML - files with index, search and table of contents. Works even locally without a web server.
Docx - OOXML format used in MS Word. Suitable for printing and exporting to PDF.
PDF document suitable for printing.
XML which can be processed later by other tools

You can define your own template to customize the output. Simple macro language was developed to enable user to change output look.

Of course, you can customize the existing templates. Moreover, VSdocman uses special language files for output localization. There are several built-in languages including English, German, French, Spanish, Portuguese, Hebrew and others. You can easily add any other language just by editing a simple text file.

VSDOCMAN LICENSE AGREEMENT

IMPORTANT - READ THESE TERMS CAREFULLY BEFORE INSTALLING THIS SOFTWARE. BY INSTALLING OR USING THIS SOFTWARE, YOU ACKNOWLEDGE THAT YOU HAVE READ THIS LICENSE AGREEMENT, THAT YOU UNDERSTAND IT, AND THAT YOU AGREE TO BE BOUND BY ITS TERMS. IF YOU DO NOT AGREE TO THE TERMS AND CONDITIONS OF THIS LICENSE AGREEMENT, PROMPTLY EXIT THIS PAGE WITHOUT INSTALLING THE SOFTWARE. THE SOFTWARE PROVIDED HEREUNDER WILL EXPIRE AFTER FOURTEEN (14) DAYS FROM INSTALLATION. THE PURCHASE OF A SOFTWARE KEY IS REQUIRED FOR USE OF THE SOFTWARE AFTER THE FOURTEEN (14)-DAY TRIAL PERIOD.

LICENCE TERMS FOR VSDOCMAN (for the purposes of this license document henceforth known as 'the Software')

1. Grant of License for Registered Users

Helixoft, grants you a non-exclusive, non-transferable license to use the program with which this license is distributed (the "VSdocman"), including any documentation files accompanying the Software ("User Guide") on a single server (if the Software is server based) or personal computer to support up to the number of simultaneous users for which you have paid the license fee, and to make one backup copy of the Software, provided that:

I.the Software is installed on only one server or personal computer;

II.the Software is NOT modified;

III. all copyright notices are maintained on the Software; and

IV.you agree to be bound by the terms of this License Agreement.

The Software and Documentation shall be used only by you, only for your own personal or internal business use and not in the operation of a service bureau or for the benefit of any other person or entity.

2. Ownership

You have no ownership rights in the Software. Rather, you have a license to use the Software as long as this License Agreement remains in full force and effect. Ownership of the Software, Documentation and all intellectual property rights therein shall remain at all times with Helixoft. Any other use of the Software by any person, business, corporation, government organization or any other entity is strictly forbidden and is a violation of this License Agreement.

3. Copyright

The Software and Documentation contain material that is protected by laws of Slovak Republic, and by international treaty provisions. All rights not granted to you herein are expressly reserved by Helixoft. You may not remove any proprietary notice of Helixoft from any copy of the Software or Documentation.

4. Restrictions

You may not publish, display, disclose, rent, lease, modify, loan, distribute, or create derivative works based on the Software or any part thereof. You may not reverse engineer, decompile, translate, adapt, or disassemble the Software, nor shall you attempt to create the source code from the object code for the Software. You may not transmit the Software over any network or between any devices, although you may use the Software to make such transmissions of other materials. You may transfer the Software to other computers you own as long as you only use it on one computer at a time.

5. Confidentiality

You acknowledge that the Software contains proprietary trade secrets of Helixoft and you hereby agree to maintain the confidentiality of the Software using at least as great a degree of care as you use to maintain the confidentiality of your own most confidential information. You agree to reasonably communicate the terms and conditions of this Software License Agreement to those persons employed by you who come into contact with the Software, and to use reasonable best efforts to ensure their compliance with such terms and conditions, including, without limitation, not knowingly permitting such persons to use any portion of the Program for the purpose of deriving the source code of the Program or defeating the Key.

6. Limited Warranty

HELIXOFT WARRANTS FOR A PERIOD OF THIRTY (30) DAYS AFTER PURCHASE THAT THE SOFTWARE WILL OPERATE SUBSTANTIALLY IN ACCORDANCE WITH THE DOCUMENTATION. SHOULD THE SOFTWARE NOT SO OPERATE, YOUR EXCLUSIVE REMEDY, AND HELIXOFT'S SOLE OBLIGATION UNDER THIS WARRANTY, SHALL BE, AT HELIXOFT'S SOLE DISCRETION, CORRECTION OF THE DEFECT OR REFUND OF THE PURCHASE PRICE PAID FOR THE SOFTWARE. ANY USE BY YOU OF THE SOFTWARE IS AT YOUR OWN RISK. THIS LIMITED WARRANTY IS THE ONLY WARRANTY PROVIDED BY HELIXOFT REGARDING THE SOFTWARE. EXCEPT FOR THE LIMITED WARRANTY ABOVE, THE SOFTWARE IS PROVIDED "AS IS." TO THE MAXIMUM EXTENT PERMITTED BY LAW, HELIXOFT DISCLAIMS ALL OTHER WARRANTIES OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. HELIXOFT DOES NOT WARRANT THAT THE FUNCTIONS CONTAINED IN THE SOFTWARE WILL MEET ANY REQUIREMENTS OR NEEDS YOU MAY HAVE, OR THAT THE SOFTWARE WILL OPERATE ERROR FREE, OR IN AN UNINTERRUPTED FASHION, OR THAT ANY DEFECTS OR ERRORS IN THE SOFTWARE WILL BE CORRECTED, OR THAT THE SOFTWARE IS COMPATIBLE WITH ANY PARTICULAR PLATFORM. SOME JURISDICTIONS DO NOT ALLOW THE WAIVER OR EXCLUSION OF IMPLIED WARRANTIES SO THEY MAY NOT APPLY TO YOU.

7. Limitation of Liability

IN NO EVENT WILL HELIXOFT BE LIABLE TO YOU OR ANY THIRD PARTY FOR ANY INCIDENTAL OR CONSEQUENTIAL DAMAGES (INCLUDING, WITHOUT LIMITATION, INDIRECT, SPECIAL, PUNITIVE, OR EXEMPLARY DAMAGES FOR LOSS OF BUSINESS, LOSS OF PROFITS, BUSINESS INTERRUPTION, OR LOSS OF BUSINESS INFORMATION) ARISING OUT OF THE USE OF OR INABILITY TO USE THE PROGRAM, OR FOR ANY CLAIM BY ANY OTHER PARTY, EVEN IF HELIXOFT HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. HELIXOFT'S AGGREGATE LIABILITY WITH RESPECT TO ITS OBLIGATIONS UNDER THIS AGREEMENT OR OTHERWISE WITH RESPECT TO THE SOFTWARE AND DOCUMENTATION OR OTHERWISE SHALL NOT EXCEED THE AMOUNT OF THE LICENSE FEE PAID BY YOU FOR THE SOFTWARE AND DOCUMENTATION. BECAUSE SOME STATES/COUNTRIES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES, THE ABOVE LIMITATION MAY NOT APPLY TO YOU.

8. Export Restrictions

THIS LICENSE AGREEMENT IS EXPRESSLY MADE SUBJECT TO ANY LAWS, REGULATIONS, ORDERS, OR OTHER RESTRICTIONS ON THE EXPORT FROM THE SLOVAK REPUBLIC OF THE SOFTWARE OR INFORMATION ABOUT SUCH SOFTWARE WHICH MAY BE IMPOSED FROM TIME TO TIME BY THE GOVERNMENT OF THE SLOVAK REPUBLIC. YOU SHALL NOT EXPORT THE SOFTWARE, DOCUMENTATION, OR INFORMATION ABOUT THE SOFTWARE AND DOCUMENTATION WITHOUT CONSENT OF HELIXOFT AND COMPLIANCE WITH SUCH LAWS, REGULATIONS, ORDERS, OR OTHER RESTRICTIONS.

9. Termination

This License Agreement is effective until it is terminated. You may terminate this License Agreement at any time by destroying or returning to Helixoft all copies of the Software and Documentation in your possession or under your control. Helixoft may terminate this License Agreement for any reason, including, but not limited to, if Helixoft finds that you have violated any of the terms of this License Agreement. Upon notification of termination, you agree to destroy or return to Helixoft all copies of the Software and Documentation and to certify in writing that all known copies, including backup copies, have been destroyed. All provisions relating to confidentiality, proprietary rights, and non-disclosure shall survive the termination of this Software License Agreement.

10. General

This License Agreement shall be construed, interpreted and governed by the laws of the Slovak Republic without regard to conflicts of law provisions thereof. The exclusive forum for any disputes arising out of or relating to this License Agreement shall be an appropriate court sitting in Slovak Republic. This License Agreement shall constitute the entire Agreement between the parties hereto. Any waiver or modification of this License Agreement shall only be effective if it is in writing and signed by both parties hereto. If any part of this License Agreement is found invalid or unenforceable by a court of competent jurisdiction, the remainder of this License Agreement shall be interpreted so as to reasonably effect the intention of the parties.

Helixoft
Tomasikova 14
080 01 Presov
Slovak Republic
http://www.helixoft.com