how shall I document the use of GET or POST in a controller method?

Question

I am searching for a best-practice-way to document my controller methods in php. I was wondering how I should document my POST and GET requirements (I used REQUEST here to show I need it for both ways).

i.e. see this method:

public function login(){

    $username = $_REQUEST['username'];
    $password = $_REQUEST['password'];
    $stay_loggedin = $_REQUEST['stay-loggedin'];

    $user = new usermodel();
    if ($user->login($username, $password, $stay_loggedin) ) return <something>;
    else return page_not_allowed;
}

It would be great if someone can tell me a way which is php-doc compatible... I mean @param wouldn't be the right way, woudldn't it?

Shall I document the required usermodel class as well? And how?

thanks for your help

Answer 1

For documenting GET/POST methods you can do like:

/**
 * Function to Login a user
 *
 * Requires $_POST['username'] and $_POST['password']
 * Optional $_REQUEST['stay-loggedin'] 
 * 
 * @return void
 */
public function login(){

    $username = $_REQUEST['username'];
    $password = $_REQUEST['password'];
    $stay_loggedin = $_REQUEST['stay-loggedin'];

    $user = new usermodel();
    if ($user->login($username, $password, $stay_loggedin) ) return ;
    else return page_not_allowed;
}

And you could document the usermodel class in usermodel class file itself. Hope it helps