Code Documentation in .Net Projects

whether you are developing personal or enterprise applications, you must document from the smallest unit (methods) to the largest unit (libraries, modules, layers, etc.) of existing code. preparing this document is an important factor in the adaptation of software engineers’ and projects’ future.

in general, we refrain from writing code descriptions in method level and prefer writing descriptions in class level. sometimes we are even postponing it. in my post, we’ll try to obtain a code documentation file(.chm) or site(.html) gathered in one place for xml-based written descriptions inside visual studio. i will show you how it’s done with sandcastle help file builder . this is a quite popular tool used in .net projects.

installation : firstly we’re downloading setup file via link on codeplex page of sandcastle help file builder tool. this setup file consist of more setup file and you will do a guided installation with it. you should pay attention each installation step and do installations one by one.

now we finished the installation. we can create a operable code help file(.chm) on windows or web-based documentation. we can do this with sandcastle help file builder gui or visual studio project template. if you ask me, being via visual studio is much easier and it provide opportunity for some additional customizations. also, all project components is so good being in a single vs solution .

sandcastle help file builder gui

let’s create a sample project to create documentation file. i will create . html and .chm code doc. file for bugtracker that i coded project. open you project and add documentation project on solution in the way that you see below.

we must be insert doc. source in added doc. project. namely we’ll add libraries(.dll) that we want to create document file on project. you can use in project’s properties for documentation project’s setting and changing output directories of it. in following the photo showing this case

then build the project and here’s doc. files created. you can see files in \help directory and my created files in the links below:

web-based documentation sample: http://doc.app.yemrekeskin.com

.chm code documentation: http://doc.app.yemrekeskin.com/bugtracker.doc.chm

alternative tools:

• http://ndoc.sourceforge.net
• http://www.techrepublic.com/blog/five-apps/five-documentation-apps-for-net-developers
• http://theboxsoftware.com/products/live-documenter
• http://revaxarts-themes.com/documenter you can produce one page html for our projects with this tool. also, you can publish produced html page on subdomain of our project (doc.project.com) -good idea- or load github project page

that’s all from my article, so i hope this has been helpful.