DOXYGEN COMMENT STRUCTS HOW TO
DOXYGEN COMMENT STRUCTS SOFTWARE
DOXYGEN COMMENT STRUCTS CODE

You still should comment private members for IntelliSense support. By default Doxygen does not document private members, so these will not show up in your generated documentation even if you comment them.Here is a link to the complete list of XML tags that Doxygen supports. I have found that simply filling out the Visual Studio-generated stubs usually gives me excellent results, but the C# language specification defines a number of additional XML documentation comment tags.

DOXYGEN COMMENT STRUCTS CODE

In addition to making Doxygen documentation generation possible, commenting your code this way is what lets IntelliSense provide parameter information in Visual Studio, so your team should already be doing it. Would get the following comment stub generated: /// The stub for a method includes the summary block as above, but also lines for the parameters and return value (if they exist), so this silly example method: public string DoThis(string s1, string s2, out string s3)

The stub for a class, field or property will simply be: /// Īnd you would fill in a brief description in the line in the middle. If you have XML documentation comments enabled via the Tools->Options menu, starting a new line immediately above a class or member definition and typing '///' will cause Visual Studio to create a stub XML documentation comment. Doxygen supports multiple formats for the comment blocks it uses to generate documentation (Javadoc, Qt, C# XML, etc.), but because Visual Studio has native support for C# XML comments for classes and class members, I recommend using it. The first step, and maybe the hardest if you have to convince recalcitrant developers to go along, is to document the code.

Generating the final compiled HTML output.

The rest of this post is split into three sections: What this means is that if you can get your developers to comment their code, you can generate a decent body of documentation. If they don't have good documentation of what a custom workflow activity does and the inputs it expects, they're likely to get unexpected results when using it.īut assuming you convince your developers of the need to generate documentation, you may still have a problem in that it's not something that comes easily to them, so how can you make it easier? The obvious answer is to generate documentation based on the source code itself, and that's where Doxygen comes in.ĭoxygen is the de facto standard tool for generating documentation from annotated C++ sources, but it also supports other popular programming languages such as C, Objective-C, C#, PHP, Java, Python, IDL (Corba and Microsoft flavors), Fortran, VHDL, Tcl, and to some extent D. For example, think of a situation in which you have primarily functional consultants building workflows. When a developer prepares these, the people who work with the activities later may very well not have access to the source code, and even if they do, they may not fully understand it. The reasoning - excuse, really - of the first point fails spectacularly when we look at Dynamics CRM custom workflow activities.

Second, a typical developer has better coding skills than writing skills. First, in most situations where code isn't being packaged and sold, anybody who needs to work with something that's already been written will likely have access to the source code (including comments), so formal documentation isn't absolutely necessary. (True story - as a brash young developer, I was quick to irritate a business analyst on my team by telling him things like 'documentation costs extra.') If you think about it, this lack of desire to document code kind of makes sense.

DOXYGEN COMMENT STRUCTS SOFTWARE

Put simply, getting software documented properly after it's written is a pain.ĭevelopers typically don't enjoy preparing documentation, and even if you can get them to document it initially, keeping it updated is always a challenge.

DOXYGEN COMMENT STRUCTS HOW TO

CalculateDateByBusinessDays.cs (2.05 kb)Īnd the final output will be this generated CHM file: LucasWorkflowDemo.chm (76.94 kb).Īlthough this sample is focused on documenting an assembly that is used as part of a Dynamics CRM solution, the overall documentation approach and techniques are applicable to any C# project.īefore we look at how to document code using Doxygen, let's step back and take look at the broader problem we need to solve.

(Doxygen can actually generate documentation in a variety of different formats, but I'm partial to CHM files because they're entirely self-contained.) For this example, I have a project that consists of these three C# files: In this post I will show how to document a Dynamics CRM 2011 custom workflow activity assembly and use Doxygen to generate a compiled HTML (CHM) help file.

Doxygen comment structs