TalkPHP
 
 
Account Login
Latest Articles
» The basic usage of PHPTAL, a XML/XHTML template library for PHP
» Vulnerable methods and the areas they are commonly trusted in.
» Simple way to protect a form from bot
» The Basics On: How Session Stealing Works
» How to keep your forms from double posting data
IRC Channel
IRC Speech Bubble Join the friendly bunch on IRC...
(#TalkPHP on Freenode)

...Also available via a web interface.

See this thread for information on the TalkPHP Free Hugs Initiative™. Subject to availability.
Associates
Associates
CSS Tutorials
Reply
 
LinkBack Thread Tools Search this Thread Display Modes
Old 05-12-2009, 02:36 AM   #1 (permalink)
The Addict
 
Enfernikus's Avatar
 
Join Date: Jun 2008
Posts: 335
Thanks: 2
Enfernikus is on a distinguished road
Default 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.
Enfernikus is offline  
Reply With Quote
Old 05-12-2009, 02:47 AM   #2 (permalink)
Wizard
Top Contributor 
 
Village Idiot's Avatar
 
Join Date: Sep 2007
Posts: 1,299
Thanks: 17
Village Idiot is on a distinguished road
Default

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

Village Idiot is offline  
Reply With Quote
Old 05-13-2009, 09:12 PM   #3 (permalink)
The Addict
 
Enfernikus's Avatar
 
Join Date: Jun 2008
Posts: 335
Thanks: 2
Enfernikus is on a distinguished road
Default

Thanks, I'm now implementing that style of commenting
Enfernikus is offline  
Reply With Quote
Old 07-03-2009, 10:59 AM   #4 (permalink)
The Visitor
 
Join Date: Jul 2009
Posts: 1
Thanks: 0
bmontuelle is on a distinguished road
Default

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/
bmontuelle is offline  
Reply With Quote
Reply



Currently Active Users Viewing This Thread: 1 (0 members and 1 guests)
 
Thread Tools Search this Thread
Search this Thread:

Advanced Search
Display Modes

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

vB code is On
Smilies are On
[IMG] code is On
HTML code is Off
Trackbacks are On
Pingbacks are On
Refbacks are On

Similar Threads
Thread Thread Starter Forum Replies Last Post
help me figure out this date thing sarmenhb Absolute Beginners 5 09-15-2008 04:20 PM
whats wrong? - i know i missed some simple thing but well help please :) codefreek Absolute Beginners 22 06-27-2008 08:29 AM
All roads lead to the forum? vujsa Feedback 11 01-06-2008 09:26 PM
help me with this href thing meshi General 3 10-17-2007 01:39 PM


All times are GMT. The time now is 08:30 AM.

 
     

Powered by vBulletin® Version 3.6.8
Copyright ©2000 - 2013, Jelsoft Enterprises Ltd.
Search Engine Optimization by vBSEO 3.1.0
Inactive Reminders By Icora Web Design