05-12-2009, 02:47 AM
|
#2 (permalink)
|
|
Wizard
Join Date: Sep 2007
Posts: 1,299
Thanks: 17
|
I would suggest looking at other software's style of documentation (MSDN's docs are the best I've ever seen). For the big programs I write, I do something like this (examples are in C++, but should be readable for a PHP programmer)
Code:
/*---------------------
Function name: getCirclePos1
Purpose: Returns the greater value a center-radius formula (solved for Y)
Paramaters:
int x,y: The x any y coords of the center of the circle.
int rad: The radius of the circle.
int x2: The X position to get the Ys for.
Returns: What would be Y on a graph,
Version: 1.1
Level: Core
NOTES:
-Is a helper function, should only be called where bad number can not be entered.
-Placing x2 as an X value where the circle does not lie will try to return a non-real number
and throw an exception for getting the square root of a negitave number.
---------------------*/
int getCirclePos1(int x, int y, int r, double x2)
{
return (int)sqrt((double)(-pow(x-x2,2.0)+pow(r,(double)2.0)))+y;
}
Along with things the programmer should know, I would also put bugs in the notes section. I also add a "to do" list when applicable. Level may not be applicable unless your framework uses a multi-tiered architecture.
For classes, I do something like:
Code:
/****************************
Class Object_properties
Description: Containes the essental parts of every object. To be directly implimented
in no higher level than game core
Version: 1
Added on initial build
Level: Engine Core
*****************************/
class Object_properties
{
public:
float xpos,ypos;
int width,height;
template <typename Object_properties_child>
bool IsColiding(Object_properties_child other);
float DistanceFrom(Object_properties);
void
ChangeXRelitave(float x),
ChangeYRelitave(float y),
changePositionRelitave(float x,float y);
void
ChangeXAbsolute(float x),
ChangeYAbsolute(float y),
changePostitionAbsolute(float x,float y);
void
placeOnMap(float x,float y),
Redefine(int x, int y, int w, int h);
void move(int dir);
SDL_Surface *face;
void Draw(SDL_Surface *),
DrawAll(SDL_Surface *screen);
SDL_Surface
* LoadFullImg(const char *),
* LoadFullImg(const char *,int r,int g,int b),
* LoadPartImg(const char *,int w,int h,int x,int y),
* LoadPartImg(const char *,int w,int h,int x,int y,int r,int g,int b);
int drawW, drawH, drawStartX, drawStartY;
Object_properties();
};
|
|
|
|