TalkPHP - One thing lead to another

TalkPHP (http://www.talkphp.com/forums.php)

- The Lounge (http://www.talkphp.com/lounge/)

- - One thing lead to another (http://www.talkphp.com/lounge/4266-one-thing-lead-another.html)

One thing lead to another

Well, I've been using my framework on all my sites so have my friends ( I told them about it, they used it and liked it ) so the story goes as follows:

The framework was used, I and my friends were too busy to upgrade the past client's websites and so they hire a new coder ( can't blame em right? ) so the coder comes and lo and behold, he doesn't know what the hell he's doing! So what does he do? Complain. The client gives him my friends ( or my ) email and the conversation takes place.

So by way of quasi-diffusion my framework has been put into use, and requires documentation.

http://docs.nrgframework.com

I've never had to write documentation for anything, so if I could get tips and such that'd be great.

P.S. The main site doesn't work on IE most of the people who'll be visiting probably won't be using IE or even configuring their download they'll just be Dling the complete package as to why exactly it's there...aestheticism.

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

};

Thanks, I'm now implementing that style of commenting

Hi,

Here we use phpDoc to document our code. Like Village Idiot's way of handling doc it uses comments in code, and it is very similar to Java's docblock syntax

/**
* This describe function usage
*
* @param int $id Parameter description
* @return mixed Return desc
*/

The same bloc repeats for classes, modules (altough this doesn't realy exists in PHP) , files, etc.

The main advantage is it has a parser that can build documentation in HTML format straight from your code !

Mor information on http://www.phpdoc.org/