Add function-level documentation

[mjordan]

I can't find any reference in the PSR standards for documenting methods/functions (although I didn't look too hard). If PSR doesn't provide any guidance, I recommend we adopt Drupal's documentation style (https://www.drupal.org/coding-standards/docs#functions).

[MarcusBarnes]

Section 7 - Conclusion of http://www.php-fig.org/psr/psr-2/ indicates that recommendations for comments and documentation blocks were intentionally omitted (for the time being). Thus, I second your suggestion to use Drupal's documentation style for methods and functions.

It might be useful to put together existing PHP Code Sniffer sniffs for PSR2 and add additional sniffs that cover Drupal's function and method documentation style. Are there any parts of Drupal's style recommendations that we wouldn't want to use for MIK? If there is no reason not to do so, we could use PHP Code Sniffer sniffs that check against Drupal's coding standards.

[mjordan]

I can't think of any Drupalisms that we wouldn't want in our code-level documentation. Since D.O. API docs are based on Doxygen, I wonder if we can use that to generate docs. Is worth trying? There is a Drupal module for generating docs at api.drupal.org, but AFAICT it creates Drupal nodes, not static HTML we can host on the github wiki.

[MarcusBarnes]

Having spent some time working on another project today, I'm reminded how useful it is to have developer reference that is easily searchable like Drupal's API reference. Here are some additional automatic tools for generating developer documentation of this sort. It's becoming clearer to me that not having a good reference for developers for projects of a certain size and complexity can be a hindrance to community contributions. Furthermore, using automatic reference generation tools will make us enforce our code-level documentation practices. I'd like to see an initial go at creating basic generated-docs for the 1.0 milestone to make it easier for those interested in making contributions.