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 :
- write a small commented text inside each function ?
- write Man/INFO file
- 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/functionfoo
Code:
libName/file/functiongoo
while functionfoo will be an example (only a small part) for one of my functions.
Quote:
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 :-(