Thread: How to write documenation for a Library ?

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

    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
    28,413
    Have you considered something like Doxygen?
    Quote Originally Posted by Bjarne Stroustrup (2000-10-14)
    I get maybe two dozen requests for help with some sort of programming or design problem every day. Most have more sense than to send me hundreds of lines of code. If they do, I ask them to find the smallest example that exhibits the problem and send me that. Mostly, they then find the error themselves. "Finding the smallest program that demonstrates the error" is a powerful debugging tool.
    Look up a C++ Reference and learn How To Ask Questions The Smart Way

  3. #3
    Registered User
    Join Date
    Apr 2007
    Posts
    111
    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, 06: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-21-2002, 12:01 AM
  5. My graphics library
    By stupid_mutt in forum C Programming
    Replies: 3
    Last Post: 11-26-2001, 06:05 PM