Skip to content

GitLab

  • Projects
  • Groups
  • Snippets
  • Help
    • Loading...
  • Help
    • Help
    • Support
    • Community forum
    • Submit feedback
    • Contribute to GitLab
  • Sign in
C
Core
  • Project overview
    • Project overview
    • Details
    • Activity
    • Releases
  • Repository
    • Repository
    • Files
    • Commits
    • Branches
    • Tags
    • Contributors
    • Graph
    • Compare
  • Issues 933
    • Issues 933
    • List
    • Boards
    • Labels
    • Service Desk
    • Milestones
  • Operations
    • Operations
    • Incidents
  • Analytics
    • Analytics
    • Repository
    • Value Stream
  • Wiki
    • Wiki
  • Snippets
    • Snippets
  • Members
    • Members
  • Collapse sidebar
  • Activity
  • Graph
  • Create a new issue
  • Commits
  • Issue Boards
  • Development
  • Core
  • Issues
  • #1559

Closed
Open
Opened Jan 29, 2020 by colemanw@colemanwOwner

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:

image

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.

Edited Jan 29, 2020 by colemanw
To upload designs, you'll need to enable LFS and have an admin enable hashed storage. More information
Assignee
Assign to
None
Milestone
None
Assign milestone
Time tracking
None
Due date
None
Reference: dev/core#1559