Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

Visual Studio with DoxyGen for documentation, or should we use something else? [closed]

We are currently using DoxyGen to document code written in C/C++, PHP and Java. To have a consistent environment it would be nice to use it for C# documentation as well.

However we are wondering:

  • Do you see any advantages in the generated documentation layout or structure using something other than DoxyGen? We are generating documentation for external developers who are experienced with C# and the .NET platform. Maybe they are used to a certain documentation format?
  • How well integrated can DoxyGen be with Visual Studio? Is there something which enables a one-click generation of documentation from inside the IDE?
  • Is some other documentation system more integrated with Visual Studio?
like image 598
Deleted Avatar asked Jan 08 '10 14:01

Deleted


People also ask

Do I need doxygen?

As already explained, Doxygen is a tool that helps in writing reference documentation for different programming language such as Java, C, C++, C#, IDL, D etc. updating of the old configuration file, etc.

When should I take doxygen?

Doxygen (/ˈdɒksidʒən/ DOK-see-jən) is a documentation generator and static analysis tool for software source trees. When used as a documentation generator, Doxygen extracts information from specially-formatted comments within the code.


1 Answers

The default way of documenting C# code in Visual Studio is by XML documentation comments. In my opinion this is the best way to go for C# code because support for this is already integrated in Visual Studio (comment tag auto completion, warning about missing or incorrectly spelled parameters, ...). To document a method, just type three slashes (///) in front of the method body, and Visual Studio will insert an empty comment template for you to fill, like so:

/// <summary> ///  /// </summary> /// <param name="bar"></param> private void Foo(int bar) {     // ... } 

You can configure Visual Studio to generate an XML file from all the comments, which would then be fed into a documentation generator like Sandcastle. If you want to use Doxygen, this is no problem as it supports parsing XML comments.

To sum up: I would recommend to use XML comments over special Doxygen comments for C# code. This way you have all the options. You can generate documentation in the standard Doxygen layout your organization is familiar with (becauses Doxygen supports XML comments) plus you have the option to generate documentation in a format known to .NET developers (with Sandcastle and Sandcastle Help FileBuilder).

Ah, and also try GhostDoc...

like image 147
Christian Avatar answered Sep 28 '22 03:09

Christian