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?

  • @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 – Sad CRUD Developer 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.

| improve this answer | |

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