My project uses FoundationPress, a WordPress starter theme. I use Github and update my project from the parent repository with an upstream remote when the community improves the code. For the record, I've programmed a long time but almost always alone, and I'm very inexperienced with docblocks and in-code documentation. I know to some extent this may be opinion based as that seems to be the trend searching other answers, but I feel like I'm not grasping proper usage.
The parent project uses PHP Docblocks that look like this on PHP files, always only once per file, for example:
/**
* Brief File Description
*
* @package FoundationPress
* @since FoundationPress 1.0.0
*/
When I add new PHP files of my own, I've been adding a similar block but using the name for my project instead:
/**
* Brief File Description
*
* @package MyProject
* @since MyProject 0.1.0
*/
Sometimes, I update an existing file with my own functions. I've been putting @since above those functions, so it is like this:
/**
* Brief File Description
*
* @package FoundationPress
* @since FoundationPress 1.0.0
*/
function foo() { ... }
function bar() { ... }
/**
* My Function Description
*
* @since MyProject 0.1.0
*/
function my_foo() { ... }
Other times, I update an existing function - I just leave the docblock alone for those, but I wonder if I should be updating anything.
- Is there a best practice or at least commonly accepted way to handle this situation (a forked project that is keeping up to date with its parent repository) so my code is more useful to other programmers?
- There seem to be a lot of other docblock parameters and options, like docblocks for every function. Is there a recommended level of detail I should strive for?
- Is there a best practice for also adding similar documentation on other kinds of files (SCSS, JS, etc) in my project? The parent project doesn't seem to have any, but I'd be interested in adding some.
My goal is to create code & in-code documentation in a format that coworkers or future maintainers may find useful in the future.
