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:
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
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:
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!
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:
C#:
* 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
C#:
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:
C#:
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!