Transcript Integratie NDoc help documentatie in Visual Studio 2005

Integratie NDoc help
documentatie in
Visual Studio 2003 & 2005
Fons Sonnemans
Freelance .NET Expert and Trainer
Reflection IT
SDN 1 April 2004
Agenda
XML Documentation
• Using NDoc
• NDoc and Visual Basic 2005
• Other Tools
•
Software Development Event: Integratie
Documenting Assemblies
Designing object-oriented software is hard, and
designing reusable object-oriented software is
even harder.
• Assemblies can only be reused when they are
well documented.
• Documenting assemblies is difficult and very
time consuming.
• The documentation should be easily accessible.
•

Visual Studio Online Help System
•

Context Sensitive (F1), Dynamic Help, Contents, Search,
Index and Filtering
IntelliSense
Software Development Event: Integratie
Visual Studio Online Help System
Software Development Event: Integratie
Document as you go
Reflection IT
XML Documentation
C# XML Documentation (///)
Software Development Event: Integratie
Build Comment Web Pages
Software Development Event: Integratie
VB.NET XML Documentation
•
The VBCommenter is an add-in for Visual Studio .NET
2003 that enables the following three things:


•
The Ability to automatically generate XML comment headers for
classes, methods and properties in the VB .NET editor similar to
what the C# editor automatically generates.
The generation of the XML comment file to go along with your VB
assemblies at build time. This file can also be used with the
"Custom Help Builder" PowerToy to build a full help package for
your class library assemblies.
Download

http://www.gotdotnet.com/workspaces/workspace.aspx?id=112b
5449-f702-46e2-87fa-86bdf39a17dd
Software Development Event: Integratie
VBCommenter
•
You can insert an XML comment by typing three
apostrophes (') before a class definition or member.
•
When you press Enter, the XML document template is
automatically generated for you.
Software Development Event: Integratie
XML documentation tags
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
<c>
<para>
<see>
<code>
<param>
<seealso>
<example>
<paramref>
<summary>
<exception>
<permission>
<value>
<include>
<remarks>
<list>
<returns>
You can get a list of XML documentation tags from MSDN at
http://msdn.microsoft.com/library/enus/csref/html/vclrfTagsForDocumentationComments.asp
Software Development Event: Integratie
Build Project
•
Once you have commented your code, rebuild your class(es)
and you will be able to find an XML document with the same
name as your project in the bin folder of your project.
Software Development Event: Integratie
Reflection IT
Using NDoc
NDoc
NDoc generates class library documentation for
C# code and VB code (with an add-on tool like
VBCommenter).
• Open Source
•

•
http://ndoc.sourceforge.net/
Input:


From .NET assemblies (DLL, EXE).
And the XML documentation files generated by the C#
compiler or add-on.
Software Development Event: Integratie
NDoc GUI
•
New Project -> Add Assembly
•
Documentation Type





JavaDoc
LaTeX
MSDN (.chm)
VS.NET 2003
XML
Software Development Event: Integratie
Documentation Type - VS.NET 2003
The VS.NET documenter creates compiled Html
Help version 2 titles similar in format to the .NET
Framework SDK collection. Html Help 2 is the
help technology used by the Visual Studio.NET
help system as well as by newer version of
MSDN and the SDK documentation.
• Documentation generated with this documenter
can be integrated into Visual Studio and MSDN.
This entails inclusion in the combined table of
contents, index and search functions, as well as
context sensitive and dynamic help from with the
Visual Studio IDE.
•
Software Development Event: Integratie
VS.NET 2003 Properties
•
Documentation Main Settings




•
CopyrightText
HtmlHelpName
OutputDirectory
Title
…
…
…
…
HtmlHelp2 Deployment


CollectionNamespace
GenerateCollectionFiles
•

…
True
Creates the H2reg.ini file
RegisterTitleAsCollection
Software Development Event: Integratie
True
HTML Help Compilers
•
HTML Help Version 2: If you plan to create
help titles that integrate with the VS.NET help
system, you will need to download the Visual
Studio Help Integration Kit (VSHIK). This
download includes the compiler capable of
creating HxS help titles.

http://msdn.microsoft.com/library/enus/htmlhelp/html/hwmscextendingnethelp.asp
Software Development Event: Integratie
Build Documentation
•
Menu Documentation -> Build
Software Development Event: Integratie
H2Reg (beta version 1.4.3)
•
H2Reg.exe is a small utility (177K), that allows
you to register MS Help 2.x Collections:
Namespaces, Titles, Plug-ins, and Filters
without using MSI (Microsoft Installer).

•
http://www.helpware.net/mshelp2/h2reg.htm
Not freeware



H2Reg download is a full working version. It will never
expire.
H2Reg is Free for personal use.
H2Reg must be purchased if included as a part of an
installation solution that you will pass on to others.
•
•
$50 when number of shipped products a year < 100
$100 no limit
Software Development Event: Integratie
H2Reg.ini
;
;
;
;
This file is intended for input into the H2Reg.exe help registration utility.
H2Reg.exe is a shareware product from The Helpware Group that can be integrated into
installers used for deploying html help 2 titles and collections.
H2Reg.exe can be downloaded and licensed from http://www.helpware.net
[Reg_Namespace]
SampleProject2003Collection|SampleProject2003Collection.HxC|SampleProject2003 Library
[UnReg_Namespace]
SampleProject2003Collection
[Reg_Plugin]
ms.vscc+|_DEFAULT|SampleProject2003Collection|_DEFAULT|
[UnReg_Plugin]
ms.vscc+|_DEFAULT|SampleProject2003Collection|_DEFAULT|
[Reg_Filter]
SampleProject2003Collection|SampleProject2003 Library|("DocSet"="SampleProject2003")
[UnReg_Filter]
SampleProject2003Collection|SampleProject2003 Library
[Reg_Title]
SampleProject2003Collection|SampleProject2003|1033|SampleProject2003.HxS|SampleProject20
03.HxS||||||
[UnReg_Title]
SampleProject2003Collection|SampleProject2003|1033
Software Development Event: Integratie
Deployment
•
Deploy


•
*.HxS, *.HxC, *.HxK, *.HxA, *.HxT,
*.H2Reg.ini
Register using H2Reg.exe
"C:\Program Files\Helpware\H2Reg\H2reg.exe" -r -m
CmdFile="D:\SampleProject2003Collection.h2reg.ini"

CmdFile = H2Reg.ini file
-r Register
-m Merge

-u Uninstall


Software Development Event: Integratie
Visual Studio Online Help (F1)
Software Development Event: Integratie
NDoc Console Application
•
The console application (NDocConsole.exe)
exposes the full building capability of the GUI
application and is designed to be integrated into
automated build processes.
Software Development Event: Integratie
Reflection IT
NDoc & Visual Basic 2005
Visual Basic 2005
No need for VBCommenter
• IntelliSense support
•
Software Development Event: Integratie
Class Designer - Summary
Software Development Event: Integratie
Compile NDoc in VS2005
•
Download (Latest Stable Source, 1.31) NDoc

•
http://ndoc.sf.net
Open solution in VS2005

Conversion Wizard -> Finish -> Build -> Ignore
Warnings
Software Development Event: Integratie
VS2005 and NDoc
•
NDoc Property: PlugInNamespace

•
Use H2Reg version 1.4.3

•
Try local only, not online
Issues:



•
–m option required
VS2005 Option: Help - Online

•
MS.VSCC.v80
Links to .NET 1.1 Framework
Missing 2005 template
No support for Generics
We will have to wait new version of NDoc
Software Development Event: Integratie
Reflection IT
Other tools
VSHIK – Namespace.exe
•
Unsupported Tool
Software Development Event: Integratie
FAR – H2 Utilities
•
FAR HTML is a collection of file and HTML Help
utilities for authors. If you need to quickly
manipulate HTML files, or create and edit HTML
Help 1.x or MS Help 2.x projects then FAR will
save you lots of time.
Software Development Event: Integratie
GhostDoc
•
GhostDoc is an add-in for Visual Studio.NET
2003 for automatically generating those parts
of a C# documentation comment that can be
deduced from name and type of e.g.
methods, properties or parameters.

http://www.roland-weigelt.de/ghostdoc/
Software Development Event: Integratie
Document! X
•
Document! X automates the process of creating
and maintaining documentation for a wide range
of solution elements






•
VB.NET (2003)/C#/Visual C++ .NET Projects;
Visual Basic 5 or 6 Projects;
Compiled COM Components and Controls;
COM Type Libraries;
Access, SQL Server and Oracle Databases;
XSD Schemas or implied XML Schemas
Website

http://www.innovasys.co.uk/products/documentx.asp
Software Development Event: Integratie
DocumentX - VS.NET Comment Helper
WYSIWYG Comment Editor
• Replaces NDoc and more…
•
Software Development Event: Integratie
VBdocman.NET
WYSIWYG Comment Editor
• Replaces NDoc
•
Software Development Event: Integratie
Links
•
Generating Documentation for Your Visual Basic
.NET Applications (VBCommenter)

•
NDoc – documenting .NET 2.0 assemblies

•
http://msdn.microsoft.com/library/default.asp?url=/lib
rary/en-us/dv_vstechart/html/vbgeneratingdocs.asp
http://ndoc.sourceforge.net/wiki/dotNet_2.0_Support
Integrate NDoc HTML Help in VS.NET

http://www.reflectionit.nl/NDoc.aspx
Software Development Event: Integratie
Fons Sonnemans
[email protected]
http://www.reflectionit.nl
Reflection IT
Vragen?
Fons Sonnemans
[email protected]
http://www.reflectionit.nl
Reflection IT
Bedankt voor uw aandacht