Use markdown in php docblocks
tl;dr: I propose we standardize the format of our docblocks to use markdown.
To-date, docblocks in CiviCRM haven't been very visible (or very much of anything). The APIv4 Explorer is starting to change that. For example, this docblock:
/**
* ACL (Access Control List).
*
* An ACL record consists of:
*
* - an Operation (e.g. 'View' or 'Edit')
* - a set of Data that the operation can be performed on (e.g. a group of contacts)
* - and a Role that has permission to do this operation.
*
* Creating a new ACL requires at minimum a entity table, entity ID and object_table.
*
* @see https://docs.civicrm.org/user/en/latest/initial-set-up/permissions-and-access-control
* @package Civi\Api4
*/
class ACL extends Generic\DAOEntity {Displays in the explorer like this:
I've been doing my best to make them render nicely, for example it turns ticks into bullets, @see annotations into links, and double-line-breaks into paragraphs... but that's about it so far. It would be really nice if we could fully support markdown for formatting, lists, tables, code blocks, etc. etc.
Apparently using markdown in PHP docblocks is gaining popularity. PHPStorm now supports it, as does PHPDocumentor.
I suggest we jump on that bandwagon. If there's no objections I'll add a markdown parser to the APIv4 Explorer and start using markdown syntax in more docblocks.