Code Documentation in .Net Projects
Join the DZone community and get the full member experience.
Join For Freewhether 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.
Opinions expressed by DZone contributors are their own.
Trending
-
Avoiding Pitfalls With Java Optional: Common Mistakes and How To Fix Them [Video]
-
An Overview of Kubernetes Security Projects at KubeCon Europe 2023
-
What Is Istio Service Mesh?
-
Logging Best Practices Revisited [Video]
Comments