Is there a best practice way of documenting which outside constants are used by a PHP class?
For example, I have a class that logs data to a text file. This class creates a file and puts it into a directory. The path to this directory is the constant APP_LOG_PATH. How should I document my code, so that someone can quickly look at the PHP class and know APP_LOG_PATH needs to be defined somewhere in the calling code. Something like:
/**
* Write to file
*
* @depends_on APP_LOG_PATH
* @param string The file name
* @param string The content to write
*/
static public function write_to_file($filename, $content){
file_put_contents(APP_LOG_PATH . $filename, $content);
}
You might consider using a @uses tag for it. From the description:
The @uses tag may be used to document any element (global variable, include, page, class, function, define, method, variable)
It goes on to say that it will attempt to create a backlink on the item being used, so the documentation can show what functions/methods will be using it.
One way would be to use dependency injection, which then you could document it on your injection function / parameter. Another way would be to document the constant on the define's docblock, which is a solution referenced in phpdoc: What's the proper way to document a constant