How to write documenation for a Library ?

This is a discussion on How to write documenation for a Library ? within the C Programming forums, part of the General Programming Boards category; Good Evening. I'm working on a small library (Has only 2K lines) that will help to work with Bezier Surfeces. ...

  1. #1
    Registered User
    Join Date
    Apr 2007
    Posts
    112

    How to write documenation for a Library ?

    Good Evening.

    I'm working on a small library (Has only 2K lines) that will help to work with Bezier Surfeces.
    Since i read all ready few lib that do just that i figure out that some times too much info makes your life harsh so :

    How should i write documentation for a given functions :
    1. write a small commented text inside each function ?
    2. write Man/INFO file
    3. Do some thing else ?


    This was fun ..

    so for a given foo function :
    Code:
    void * foo (type *ptr)
    {
       .
       .
       .
       bla bla bla .. 
       .
       .
       .
    
    } 
    
    void * goo (void *ptr)
    {
       .
       .
       .
       bla bla bla .. 
       .
       .
       .
    
    }
    what is better :


    Code:
    void * foo (type *ptr)
    {
     /*
      * This Function get parmeter by the type "type"
      * 
      * It will calculate and do ...
      *
      * Usage example (some C code that  explain what it does )
      *
      * more bla bla
      */ 
      .
       .
       .
       bla bla bla .. 
       .
       .
       .
    
    }
    or it will be better to create a directory structure that will hold :
    Code:
    libName/file/
    Code:
    libName/file/functionfoo
    Code:
    libName/file/functiongoo
    while functionfoo will be an example (only a small part) for one of my functions.

    Mathimatical stuff :

    A Bezier Polynom is defined by the next equation :

    B(t) = sum from {i = 0 } to n ( binom {n} {i} ) P_i (1 - t) ^ {n-i} times t^i

    While P_i is one chosen control Point .
    i is the index that run brom _0_ to 'n' while 'n' is a natural number and is the total amount of control point minus one.

    Coding
    in this function (calc_bezier(point *p, int n)) will ..

    while the *p is array of control points remmber that the line will go thru the first and the last point.

    and n is the amount of points so for the array *p.

    Code:
    {
      Point *p .
      p =(Point *) malloc (sizeof(*p) * 3);
     
      p[i].x = XValue;
      p[i].y = YValue;
      p[i].z = ZValue;
    }
    i = [0,2] or 0<=i<=2 /\ i in setR

    you will need to invoke the function using calc_bezier(p,3);
    What would you recommend ?

    P.s

    I don't even have an idea how to explain the GUI part :-(
    why Gaos didn't had a wife ?
    http://bsh83.blogspot.com

  2. #2
    C++ Witch laserlight's Avatar
    Join Date
    Oct 2003
    Location
    Singapore
    Posts
    21,743
    Have you considered something like Doxygen?
    C + C++ Compiler: MinGW port of GCC
    Version Control System: Bazaar

    Look up a C++ Reference and learn How To Ask Questions The Smart Way

  3. #3
    Registered User
    Join Date
    Apr 2007
    Posts
    112
    Thank you,..

    Didn't know about that tool (every day you learn some thing new) i guess it a good enugh solutione
    why Gaos didn't had a wife ?
    http://bsh83.blogspot.com

Popular pages Recent additions subscribe to a feed

Similar Threads

  1. Difficulty choosing graphics library
    By jdiperla in forum Game Programming
    Replies: 11
    Last Post: 02-27-2008, 05:35 PM
  2. Linker errors in VC++ 2005
    By C+/- in forum C++ Programming
    Replies: 0
    Last Post: 05-18-2007, 07:42 AM
  3. Which Sockets Library
    By ChadJohnson in forum Networking/Device Communication
    Replies: 8
    Last Post: 09-15-2004, 05:39 PM
  4. This should be the Cprogramming.com anthem!
    By Brian in forum A Brief History of Cprogramming.com
    Replies: 6
    Last Post: 01-20-2002, 11:01 PM
  5. My graphics library
    By stupid_mutt in forum C Programming
    Replies: 3
    Last Post: 11-26-2001, 05:05 PM

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21