2

I am adding documentation to PHP code using the phpDocs tool:

/**
* This is a summary
*
* This is a description
*
* @use This function is called here and here 
*/
function doSomething(){

}

I am just wondering if I want to add within this docblock a 'use' tag that says where this function doSomething() is called how do I go doing it properly?

closed as unclear what you're asking by user22815, durron597, user40980, GlenH7, gbjbaanb Jun 28 '15 at 21:55

Please clarify your specific problem or add additional details to highlight exactly what you need. As it's currently written, it’s hard to tell exactly what you're asking. See the How to Ask page for help clarifying this question. If this question can be reworded to fit the rules in the help center, please edit the question.

  • @Snowman PHP language for phpDocs tool although I thought documentation for docblocks uses a universal standard. I looked at phpDocs but found nothing. I feel on SO this question would be rejected hence asked here – BDillan Jun 11 '15 at 19:13
6

Don't do it. There is no proper way of doing it.

Documenting which places a function gets called from is a remnant of the structured programming paradigm of the seventies and the eighties. I actually do remember back in 1989 a professor asking us to document functions this way; I never heard of anyone doing such a thing ever since. This paradigm has been dead for more than two decades. We have moved on.

A function that does not stand on its own is not worth having. If a function does in fact stand on its own, then who calls it is of no concern to the function, it does not affect what the function does, nor how it does it. So, you really don't care who calls it. Anyone may call it, and they don't need permission from a doc comment to do it.

To put it in different words, a well written function is by definition a function that need not, and should not, care who calls it. By including information about who calls it in its documentation you are tempting the reader to suspect that this function may somehow be tightly coupled with these particular callers, forcing the reader to double check to make sure that in fact it is not, because tight coupling would be a terrible thing to do.

Also, the set of places that call a certain function tends to change drastically as you keep working on the code base, so this particular kind of documentation becomes outdated very fast, while at the same time it is something that you can ask your IDE at any moment by simply pressing a key combination, (it is usually called "Find References" or something similar,) and the IDE will tell you in milliseconds, and it will do that far more accurately than any documentation ever would.

So: absolutely pointless.

Not the answer you're looking for? Browse other questions tagged or ask your own question.