Documentation for a project

[Rhodan]

This doesn't seem to fit any of the existing forums so I'll blindly post here and hope I don't get beat up too badly.

I'm working on a GPL C# IO library called PiIO for the Raspberry and what I'm trying to do is document everything as I go along rather than finish the project and give up due to the sheer volume of work making documentation after the fact. The problem is I'm kind of at a loss when it comes to laying out the structure of the documentation in a way that would make sense to someone other than myself. I've tried searching for examples but all I get are little blurbs about how I should use Product X to create my documentation without any real examples of how code is documented.

I decided to use the gitHub Wiki rather than piles of Readme files though I'll probably have quite a few of those as well. I've run across many unnavigable Wikis and I want to avoid doing that. I'm hoping you folks would have some suggestions or links to what you think are well done code documenting Wiki examples.

I was thinking of dividing the docs by namespace, which would produce a TOC like:

* PiIO
  * GPIO
  * I2C
  * SPI
.. etc

Where clicking on one of the links would show everything in that part of the namespace like Methods, enums, whatever. For example, clicking on I2C would show

I2C Methods and properties

Class I2CCmd 

Properties:
None

Methods:

I2CCmd.Init()
  Success: Linux File Handle
  Error: Negative int

  PiIO uses Linux file handles to talk to I2C devices, not the device's I2C address.
    
  Example: deviceHandle = I2CCmd.Init(I2CAddress);

<More methods and properties>

Don't really know if this is a good way to show what's in the Namespace.

Also (if I can figure out how) scope the TOC to I2C to show it's children like:

PiiO
  * I2C
    * Devices
      * ADC
      * DAC
      * Sensors

I could just have the TOC show all namespaces and children all the time but I personally find that hard to navigate.

What do folks think? Better ideas or example links?

Thanks!

 

[jmcilhinney]

The first step is adding XML comments to all of your types and members. Are you doing that and you just need to know how to pull it all together?

 

[Rhodan]

Yes, got all my "///" auto comments all filled out. Always do that as I go along so it doesn't really feel like so much like I'm "documenting" rather than coding.

 

[jmcilhinney]

It's not a subject that I've really looked into for some time but there used to be a lot of talk about Sandcastle, which is Microsoft's own toolset for the task. I'm not sure that it ever quite became what many hoped it would as far as simplicity is concerned and I'm not sure whether there is a later version than this:

https://www.microsoft.com/en-us/download/details.aspx?id=10526

 

[Rhodan]

I tried it out and it produces pretty nice docs. There's no "home" page in the output but I imagine that's because I'm supposed to load it via a special viewer of some sort. Didn't get that far into it last night as I found out the MS version was abandoned and now it's open source. I grabbed the newer version which includes markdown (good for github wiki I think). Attempted a quickie - don't read the docs - shot at it but got nowhere. Going to read the docs this morning.

Hopefully it's not as opaque as Doxygen - couldn't make heads nor tails of how to work that.