TalkPHP - View Single Post

Village Idiot · 05-12-2009, 02:47 AM

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();
};