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

Question

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?

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. — Eoghan
– Eoghan, Commented May 11, 2018 at 15:02
PHPDoc isn't really suited for end-user docs. Take a look at API Blueprint or Swagger. — Alex Howansky
– Alex Howansky, Commented May 11, 2018 at 15:07
@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. — Eoghan
– Eoghan, Commented May 11, 2018 at 15:12
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. — Mike Doe
– Mike Doe, Commented May 15, 2018 at 10:05

Quetzy Garcia · Accepted Answer · 2018-05-15 09:57:11Z

4

+25

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.

answered May 15, 2018 at 9:57

Quetzy Garcia

1,8301 gold badge21 silver badges23 bronze badges

Sign up to request clarification or add additional context in comments.

Comments

Eoghan · Accepted Answer · 2018-05-18 15:41:39Z

2

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.

answered May 18, 2018 at 15:41

Eoghan

1,7713 gold badges17 silver badges36 bronze badges

2 Comments

Quetzy Garcia Over a year ago

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 /** */.

Eoghan Over a year ago

@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.

conrad10781 · Accepted Answer · 2018-05-11 18:08:38Z

0

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.

answered May 11, 2018 at 18:08

conrad10781

2,28319 silver badges17 bronze badges

2 Comments

Eoghan Over a year ago

Unfortunately this makes no difference - tried with both (optional), and OPTIONAL as noted on the doc page listed above.

ashnazg Over a year ago

That manual goes with phpDocumentor 1.x, so it's not still valid for 2.x (complete rewrite).

ashnazg · Accepted Answer · 2018-05-18 08:48:51Z

0

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.

answered May 18, 2018 at 8:48

ashnazg

6,7282 gold badges34 silver badges40 bronze badges

Comments

faintsignal · Accepted Answer · 2018-05-21 05:56:21Z

0

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.

answered May 21, 2018 at 5:56

faintsignal

1,8363 gold badges22 silver badges30 bronze badges

Collectives™ on Stack Overflow

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

5 Answers 5

Comments

2 Comments

2 Comments

Comments

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

5 Answers 5

Comments

2 Comments

2 Comments

Comments

Comments

Your Answer

Sign up or log in

Post as a guest

Related