PHPDoc - Documenting @param's without the param in the function?

phpdoc param
phpdoc param types
api documentation phpdoc
how to use phpdocumentor
phpdocumentor codeigniter
phpdocumentor laravel
php code documentation
phpdocumentor in php project

I'm currently building up some phpdoc for a restful API - and I took to using the @param doc syntax for notating required params over POST.

However, after generating the phpdoc, I noticed that it refuses to list these parameters unless they match exactly with input variables into the method itself.

@uses and @see don't look good nor make much sense here when it comes to the phpdoc output. The style/look of the doc is perfect with the @param functionality.

Is there any way to override the rules put in place by PHPDoc, and allow it to generate @param blocks in the documentation, even if the param doesn't exist in the method itself?

If you want to document your API, I suggest you use proper tools like API Blueprint or Open API Spec.

And by using Swagger, you can even use annotations (which is what you apparently want) to document the API and in turn, generate the documentation out of it.

Just don't use PHPdoc for it, because that's just mixing concepts altogether.

@param, The @param tag is used to document a single argument of a function or method. It is RECOMMENDED when documenting to use this tag with every function  Description NOTE: as of 0.4.1, @param can document phpdoc.de-style, with optional $paramname The datatype should be a valid PHP type (int, string, bool, etc), a class name for the type of object, or simply "mixed". Further, you can list multiple datatypes for a single parameter by delimiting them with the pipe (e.g. "@param int|string $p1").

You can do this by utilizing "optional". IE:

@param string $variable (optional) Blah.

See other examples at https://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.param.pkg.html .

This is to be used in the use case of when a parameter is optional, unlimited parameters, etc.

param, NOTE: as of 0.4.1, @param can document phpdoc.de-style, with optional $ example of documenting a method, and using optional description with @return. I'm currently building up some phpdoc for a restful API - and I took to using the @param doc syntax for notating required params over POST.. However, after generating the phpdoc, I noticed that it refuses to list these parameters unless they match exactly with input variables into the method itself.

You might consider using a "custom" tag, maybe @parameter, so that it is listed "as is". You won't get the same hyperlink behavior for class names as the param tag provides, but you won't be limited by the lack of parameters in the code signature itself. Maybe use an inline link tag in the parameter description that points to the class type of the parameter. Otherwise, the uses, see, or link regular tags can be on separate lines as convenient links to the classes that are your parameter types.

There is currently no way to disable the internal behavior of "actual code signature overrides param tags" logic.

Basic Syntax, @param string $example2 This is a second example. */ Summary; a one-liner which globally states the function of the documented element. Description; an  phpDocumentor Guide to Creating Fantastic Documentation. phpDocumentor Quickstart. Source code for sample1.php. Source code for sample2.php. Source code for sample3.php. phpDocumentor Tutorial. Documentable PHP Elements. phpDocumentor Tutorials. phpDocumentor Manual. phpDocumentor tags. @abstract. @access. @author. @category. @copyright

I believe you can use the same approach for documenting virtual methods as a workaround, i.e. via a @method entry in the phpDoc header for the class.

E.g.:

/**
 * ... 
 *
 * @method mixed remove(integer $pricing_group_id) Remove a group and return a JSON array with remaining groups.
 */
class YourClass {

   ...

   // see class header for phpdoc entry
    public function remove($pricing_group = null) {
        ....
    }

}

A downside is that (to my knowledge) this approach does not provide a means to enter explicit description entries for the method's parameters and return value.

PHPDoc, If you want to document your API, I suggest you use proper tools like API Blueprint or Open API Spec. And by using Swagger, you can even use  *NEW 0.4.1* complete phpdoc.de DocBlock tag support. Additions include @var, @magic, @deprec, @todo, and phpdoc.de parsing of @param. *NEW 0.4.1* package inheritance in classes *NEW* advanced linking creates a hyperlink for every element in the project *NEW* page-level documentation, package-level documentation

Alright, I'm going to answer this with the solution I've found - I appreciate all the "do not do that" answers, but still hope that someone who finds themselves in a similar situation to myself ala "this needs to be done immediately without changing the format, and we cannot allot any time to this" will find it useful in the future.

You can maintain using the @param syntax if you initialise the method with the param specified, and simply set it to null - ensuring it doesn't break any existing calls.

/**
* Remove a group
*
* @param int $pricing_group_id Required
* @return mixed JSON array with remaining groups
*/
public function remove($pricing_group = null) {
    ....
}

Your PHPDoc output will now show the param type, name, and description as normal.

Keep in mind that this is not good practice - nor is it even remotely correct practice. But it'll work until you can convince a higher-up to allot you enough time to rebuild the existing documentation on a more suitable platform.

PHPDoc Documentation, include @var, @magic, @deprec, @todo, and phpdoc.de parsing of @param. most basic element of PHPDocumentor: a Documentation block or DocBlock. PHPDoc reference¶. Basic Syntax. What is a DocBlock? Which elements can have a DocBlock; Sections

fig-standards/phpdoc-tags.md at master · php-fig/fig-standards · GitHub, See the Definitions section of the PHPDoc PSR, as those definitions apply The @param tag is used to document a single parameter of a function or method. @property tags MUST NOT be used in a PHPDoc that is not associated with a class or interface. Effects in phpDocumentor ¶ Structural Elements of type class or interface tagged with the @property tag will show an extra property in their property listing matching the data provided with this tag.

PHP Documentation Standards – Make WordPress Core, Common PHPDoc tags used in WordPress include @since , @see , @global @​param , and @return (see table below for full list). What is a DocBlock?¶ A DocBlock is a special type of comment that can provide verbose information about an element in your code. The information provided in this type of comment can be used by developers to gain understanding of the function of a given element; but it is also used by IDEs to provide (among others) auto-completion and by phpDocumentor to generate API documentation.

Documenting Classes with PHPDoc (PHP Cookbook), PHPDoc syntax is based on Javadoc. The following tags are available for use: @​access , @author, @package, @param, @return, @since, @var, and @version. After you have installed phpDocumentor you can use the phpdoc command to generate your documentation. In this document we expect that the phpdoc command is available; thus whenever we ask you to run a command it would be in the following form:

Comments
  • What about @var?
  • unfortunately still not much good - this dumps the var information into the sidebar ala uses/sees, and neglects to note the type/var name. I'm looking to have the param outlined in the exact same way that a standard @param docline would be.
  • PHPDoc isn't really suited for end-user docs. Take a look at API Blueprint or Swagger.
  • @AlexHowansky understandable - but if there were a way to override PHPDoc from checking if the param existed in the method, then it'd work exactly as intended. The doc isn't for public consumption - it's for internal use. The model files are already working through PHPDoc, so for ease of use/centralization, I'm trying to get the API working through it too. All I need to do is find a way to disable PHPDoc from checking if the param I'm noting is in the function.
  • You're mixing concerns here. And long story short - no, phpDoc won't allow to alter any of its behavior. You can try with HTML table though in the method's header.
  • Unfortunately this makes no difference - tried with both (optional), and OPTIONAL as noted on the doc page listed above.
  • That manual goes with phpDocumentor 1.x, so it's not still valid for 2.x (complete rewrite).
  • Sorry, but is just terrible advice. If upper management doesn't want to spend resources for documentation/tests/whatever, that's fine, but don't leave these types of solutions, stating that it's upper management's fault, so I'll do it like this. You can just omit the @param part altogether and document whatever you want inside the PHPdoc section /** */.
  • @QuetzyGarcia this solution does not output anything through phpdoc, which was the entire point of the exercise. And unfortunately, in the working world, you're constantly forced to rely on shitty solutions like this - with the only alternative solution being to recompile phpdoc to force it to recognise @param tags for output, when no params exist.