Question

I’m trying to write the phpdocumentor block for the following:

/**
 * daysBetween
 *
 * Returns the number of whole working days between start_date and end_date. Working
 * days exclude weekends and any dates identified in holidays.
 * Use NETWORKDAYS to calculate employee benefits that accrue based on the number of
 * days worked during a specific term.
 *
 * @param   DateTime    $startDate     Start date
 * @param   DateTime    $endDate       End date
 * @param   DateTime    $holidays,...  Optional series of dates that will be excluded
 * @return  integer    Interval between the dates
 */
public function daysBetween($startDate,$endDate) {
    //  Shift the mandatory start and end date that are referenced 
    //  in the function definition, to get any optional days
    $holidays = func_get_args();
    array_shift($holidays);
    array_shift($holidays);

$startDate and $endDate are mandatory arguments, while all instances of $holidays are optional… there might be none, one or many $holiday dates defined. The PHPDocumentor definition above gives me

Parameter $holidays,… could not be found in daysBetween()

I believe I can probably get round this by modifying the method definition to

public function daysBetween($startDate,$endDate,$holidays=NULL) {

but this feels very kludgy, and I don’t believe that I should have to change my function definition in order to document it. Does anybody have any other suggestions?

P.S. I’m using PHPDocumentor2

Answer 1

Your current syntax of

* @param   DateTime    $holidays,...  Optional series of dates that will be excluded

looks proper as per the phpDocumentor manual for the param tag [1]. This page shows that the “$holidays,…” syntax should be enough for phpDocumentor to recognize an optional parameter that does not directly appear in the code’s method signature.

This “Parameter $holidays,… could not be found in daysBetween()” response probably needs a new issue opened at the github page [2].

[1] — http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.param.pkg.html

[2] — https://github.com/phpDocumentor/phpDocumentor2/issues/424