Documentation generator

Archive
1

Is there any one that uses a doc generator such as those we use for standard c/c++ dev (doxygen) or java (javadoc). In managed code, I see that sandcastle can be used. Any tips or info about that?

regards

2

Yes Sandcastle is popular (i use it from time to time) but you still can generate documentation using doxygen as it supports C#. Here is a project that uses doxygen with C#:

http://cul.codeplex.com/

3

I like sandcastle for C# libraries, as it generates a nice documentation from the “XML documentation file”. The nice thing is, if you enable “XML documentation” (under Build in the project properties), the compiler will force you to add documentation for each public member, it will even verify variable names used in the markup.

In sandcastle you have fine control over which members are visible, f.e. you can have a public class that doesn’t show up in the user documentation. This was an option I missed in doxygen.

4

I believe GHI uses Sandcastle too: http://www.ghielectronics.com/downloads/NETMF/Library%20Documentation/Index.html

5

Ok There’s still some unclear aspect in sandcastle. In fact trying to compile my project, if I run the csc.exe compiler, I obtain some error (CS0234 and CS0246) that says that the namespace SPOT or GHIElectronics are missing… Probably there’s some settings to fill in but I do not know where

6

In fact I don’t know if csc compilation is needed since the xml documentation can be generated by VS.

7

I finally succeed. And there’s no need to run csc.exe from the command prompt. Result is quite good. This will force me to maintain an uptodate documentation and that is really cool to maintain good quality.

8

I went to download Sandcastle seeing as though a few people on here like it. On the comments though someone posted that it was not the latest version and that the new one was located elsewhere. Is the June 2010 version the one I should be using?

9

My version of SHFB is 1.9.30 from january 2012.
My version of Sandcastle is 2.6.10621.1

Hope it will help you

10

Awesome. Thank you!

11

My project with Sandcastle indicates an error, can you give me a hint why the SPOT.SerialPort a foul?
The events below is copied from the output window


-------------------------------
[Sandcastle Help File Builder, version 1.9.4.0]
Creating output and working folders...
-------------------------------
Clearing working folder...
-------------------------------
Finding tools...
Found Sandcastle tools in 'C:\Program Files\Sandcastle\'
-------------------------------
Validating and copying documentation source information
Source: C:\Progs\C#prog\fez\FEZ Mini Roborama Robot\FEZ Mini Roborama Robot\bin\Debug\FEZ Mini Roborama Robot.exe
    Found assembly 'C:\Progs\C#prog\fez\FEZ Mini Roborama Robot\FEZ Mini Roborama Robot\bin\Debug\FEZ Mini Roborama Robot.exe'
Source: C:\Progs\C#prog\fez\FEZ Mini Roborama Robot\FEZ Mini Roborama Robot\bin\Debug\FEZ Mini Roborama Robot.xml

Copying XML comments files
    C:\Progs\C#prog\fez\FEZ Mini Roborama Robot\FEZ Mini Roborama Robot\bin\Debug\FEZ Mini Roborama Robot.XML -> C:\Progs\C#prog\fez\FEZ Mini Roborama Robot\Help\Working\FEZ Mini Roborama Robot.XML
-------------------------------
Generating shared content files (en-US, English (United States))...
    Last step completed in 00:00:00.1250
-------------------------------
Generating API filter for MRefBuilder...
    Last step completed in 00:00:00.0280
-------------------------------
Generating reflection information...
[C:\Windows\Microsoft.NET\Framework\v4.0.30319\MSBuild.exe]
  MRefBuilder (v2.7.0.0)
  Copyright ¸ 2006-2012, Microsoft Corporation, All Rights Reserved
  Info: Loaded 1 assemblies for reflection and 0 dependency assemblies.
MREFBUILDER : error : Unresolved assembly reference: Microsoft.SPOT.Hardware.SerialPort (Microsoft.SPOT.Hardware.SerialPort, Version=4.1.2821.0, Culture=neutral, PublicKeyToken=null) required by FEZ Mini Roborama Robot [C:\Progs\C#prog\fez\FEZ Mini Roborama Robot\Help\Working\GenerateRefInfo.proj]
    Last step completed in 00:00:02.6550
-------------------------------

SHFB: Error BE0043: Unexpected error detected in last build step.  See output above for details.
12

Its just asking you to add a reference to that assembly to your references so it can see it. If you don’t want that assembly to appear in your documentation make sure you exclude it in the properties.

13

Thanks for your hint.
I have requested the assembly reference a reference to the DLL in the project references.
Now the generation process of the documentation no more mistakes and I can start to improve the interpretation.