Results 1 to 5 of 5

Thread: Documentation for a project

  1. #1
    .NET Framework
    .NET 4.5
    Join Date
    Apr 2015
    Posts
    35
    Rep Power
    41

    Documentation for a project

    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:

    Code:
    * 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

    Code:
    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:

    Code:
    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!

  2. #2
    .NET Framework
    .NET 4.0
    Join Date
    Apr 2011
    Posts
    1,778
    Rep Power
    137
    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?

  3. #3
    .NET Framework
    .NET 4.5
    Join Date
    Apr 2015
    Posts
    35
    Rep Power
    41
    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.

  4. #4
    .NET Framework
    .NET 4.0
    Join Date
    Apr 2011
    Posts
    1,778
    Rep Power
    137
    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/down....aspx?id=10526

  5. #5
    .NET Framework
    .NET 4.5
    Join Date
    Apr 2015
    Posts
    35
    Rep Power
    41
    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.

Similar Threads

  1. Replies: 1
    Last Post: 03-30-2016, 2:30 PM
  2. Question Some help with a project I'm on
    By AJ88 in forum Windows Forms
    Replies: 0
    Last Post: 09-16-2014, 5:33 AM
  3. Question appropriate project type?
    By Ednut in forum VS.NET General Discussion
    Replies: 5
    Last Post: 05-09-2013, 8:59 AM
  4. Question looking for assistance with a project
    By josh.robinson in forum Windows Forms
    Replies: 1
    Last Post: 03-18-2013, 4:54 AM
  5. Question help me in my project
    By kingrobbie in forum ASP.NET General Discussion
    Replies: 0
    Last Post: 10-18-2012, 8:50 AM

Bookmarks

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •