Commit 2e0e7cd1 authored by Sean Madsen's avatar Sean Madsen

Improve docblocks

parent 2394587e
......@@ -12,13 +12,11 @@ use AppBundle\Model\Library;
class PublishController extends Controller {
/**
*
* @var \AppBundle\Utils\Publisher
*/
private $publisher;
/**
*
* @var bool TRUE if the book was published without any errors
*/
private $publishSuccess;
......@@ -81,11 +79,10 @@ class PublishController extends Controller {
/**
* Send notification emails after publishing
*
* @param array $extraRecipients Array of strings for email addresses that
* should receive the notification email. If
* non are specified, then the email will be
* sent to all addresses set in the book's yaml
* configuration.
* @param array $extraRecipients
* Array of strings for email addresses that should receive the
* notification email. If non are specified, then the email will be sent to
* all addresses set in the book's yaml configuration.
*/
private function sendEmail($extraRecipients = array()) {
$subject = $this->publisher->status;
......
......@@ -17,7 +17,9 @@ class ExceptionListener {
/**
* ExceptionListener constructor.
*
* @param string $publishPathRoot
* Full filesystem path to the directory where books are to be published
*/
public function __construct($publishPathRoot) {
$this->publishPathRoot = $publishPathRoot;
......@@ -25,6 +27,7 @@ class ExceptionListener {
/**
* This method is called by some sort of Symfony magic for every exception
*
* @param \Symfony\Component\HttpKernel\Event\GetResponseForExceptionEvent $event
*/
public function onKernelException(GetResponseForExceptionEvent $event) {
......@@ -42,8 +45,12 @@ class ExceptionListener {
/**
* See if we have a redirect stored for the given URI. If so, return the full
* path to it as a string (which begins with a slash). If not, return NULL
*
* @param string $requestUri
* e.g. "/dev/en/latest/my-category/my-page"
*
* @return null|string
* e.g. "/dev/en/latest/foo/bar"
*/
private function lookupRedirect($requestUri) {
// Give up right away if the request contains two dots (for security)
......
......@@ -8,8 +8,9 @@ use AppBundle\Utils\StringTools;
class Book {
/**
* @var string The reference identifier for this book, taken from
* the name of the book's .yml file.
* @var string
* The reference identifier for this book, taken from the name of the
* book's .yml file.
*/
public $slug;
......@@ -34,7 +35,6 @@ class Book {
public $weight;
/**
*
* @var string (e.g. "Core", "Extensions") Should be in sentence case
*/
public $category;
......@@ -42,8 +42,9 @@ class Book {
/**
* Creates a book based on a yaml conf file
*
* @param string $confFile The path to the yaml configuration file which
* defines the attributes of the book.
* @param string $confFile
* The path to the yaml configuration file which defines the attributes
* of the book.
*/
public function __construct($confFile) {
$parser = new Parser();
......@@ -60,15 +61,16 @@ class Book {
}
/**
* @return bool True when the book contains multiple languages.
* @return bool
* True when the book contains multiple languages.
*/
public function isMultiLanguage() {
return count($this->languages) > 1;
}
/**
* @return integer The total number of language/version combinations defined
* for this book
* @return integer
* The total number of language/version combinations defined for this book
*/
public function countEditions() {
$sum = 0;
......@@ -79,7 +81,8 @@ class Book {
}
/**
* @return bool TRUE if the book has more than one language/version combo
* @return bool
* TRUE if the book has more than one language/version combo
*/
public function isMultiEdition() {
return $this->countEditions() > 1;
......@@ -88,7 +91,8 @@ class Book {
/**
* Selects one of the languages within the book
*
* @param string $code Two letter language code to describe the language
* @param string $code
* Two letter language code to describe the language
*
* @return Language
*/
......@@ -115,7 +119,8 @@ class Book {
*
* If validation succeeds, this function returns nothing
*
* If validation fails, this function throws an exception.
* @throws \Exception
* If validation fails
*/
public function validate() {
$illegalBookSlugs = array(
......
......@@ -18,24 +18,28 @@ class Language {
public $versions;
/**
* @var string The two letter language code for this language as
* specified by https://en.wikipedia.org/wiki/ISO_639-1
* @var string
* The two letter language code for this language as specified by
* https://en.wikipedia.org/wiki/ISO_639-1
*/
public $code;
/**
*
* @var array email addresses for people who would like to receive a
* notification any time a version within this language is
* published
* @var array
* Email addresses for people who would like to receive a notification any
* time a version within this language is published
*/
public $watchers = array();
/**
* Initialize a language with values in it.
*
* @param string $code two letter language code
* @param array $yaml language data from a book's yaml file
* @param string $code
* Two letter language code
*
* @param array $yaml
* Language data from a book's yaml file
*/
public function __construct($code, $yaml) {
$this->code = $code;
......@@ -51,7 +55,8 @@ class Language {
/**
* Set up $this->versions based on parsed yaml data in $yaml
*
* @param array $yaml Data passed into the language constructor.
* @param array $yaml
* Data passed into the language constructor.
*/
private function setupVersions($yaml) {
$latestBranch = isset($yaml['latest']) ? $yaml['latest'] : NULL;
......@@ -86,13 +91,22 @@ class Language {
*
* If validation succeeds, this function returns nothing
*
* If validation fails, this function throws an exception.
* @throws \Exception
* If validation fails
*/
public function validate() {
$this->validateCode();
$this->validateAllVersionDescriptors();
}
/**
* Check the code definied for this language to see if it's valid
*
* If validation succeeds, this function returns nothing
*
* @throws \Exception
* If validation fails
*/
private function validateCode() {
if (!LocaleTools::codeIsValid($this->code)) {
throw new \Exception("Language code '{$this->code}' is not a valid "
......@@ -103,10 +117,13 @@ class Language {
/**
* Adds a new version to this branch
*
* @param string $name (e.g. "latest", "master", "4.7", etc.)
* @param string $branch (e.g "master", "4.7", etc)
* @param array $aliases Array of strings containing names which can also be
* used to reference the version.
* @param string $name
* (e.g. "latest", "master", "4.7", etc.)
* @param string $branch
* (e.g "master", "4.7", etc)
* @param array $aliases
* Array of strings containing names which can also be used to reference
* the version.
*/
public function addVersion($name, $branch = NULL, $aliases = array()) {
$this->versions[] = new Version($name, $branch, $aliases);
......@@ -122,7 +139,8 @@ class Language {
*
* If validation succeeds, this function returns nothing
*
* If validation fails, this function throws an exception.
* @throws \Exception
* If validation fails
*/
private function validateAllVersionDescriptors() {
$descriptors = array();
......@@ -139,23 +157,32 @@ class Language {
}
/**
* The name of the language, in English (e.g. "Spanish")
* The name of the language, in English
*
* @return string
* e.g. "Spanish"
*/
public function englishName() {
return LocaleTools::getLanguageNameInLocale($this->code, 'en');
}
/**
* The native name of the language, in the language (e.g. "Español")
* The native name of the language, in the language
*
* @return string
* e.g. "español"
*/
public function nativeName() {
return LocaleTools::getLanguageNameInLocale($this->code, $this->code);
}
/**
* A string which refers to this language by both its native name and its
* English name
*
* @return string
* e.g. "español (Spanish)"
*/
public function descriptiveName() {
if ($this->code == 'en') {
return $this->englishName();
......@@ -166,7 +193,7 @@ class Language {
}
/**
* True when this language contains multiple distinct versions.
* True when this language contains multiple distinct versions
*
* @return bool
*/
......@@ -175,6 +202,8 @@ class Language {
}
/**
* Count the number of versions defined within this language
*
* @return integer
*/
public function countVersions() {
......@@ -185,8 +214,9 @@ class Language {
* Retrieves a version object defined for this language
*
* @param string $branch
* @return \AppBundle\Model\Version The first version in $versions which
* matches the specified branch
*
* @return \AppBundle\Model\Version
* The first version in $versions which matches the specified branch
*/
public function getVersionByBranch($branch) {
$chosen = NULL;
......@@ -211,8 +241,9 @@ class Language {
* which can be either a branch, or a name, or an alias.
*
* @param string $descriptor
* @return \AppBundle\Model\Version The first version in $versions which
* matches the specified descriptor
*
* @return \AppBundle\Model\Version
* The first version in $versions which matches the specified descriptor
*/
public function getVersionByDescriptor($descriptor) {
$chosen = NULL;
......
......@@ -7,9 +7,9 @@ use Symfony\Component\Finder\Finder;
class Library {
/**
*
* @var array An array (without keys) of Book objects to represent all the
* books in the system.
* @var array
* An array (without keys) of Book objects to represent all the books in
* the system.
*/
public $books;
......@@ -33,10 +33,12 @@ class Library {
* books with uasort()
*
* @param Book $a
*
* @param Book $b
* @return int - Negative when $a comes before $b.
* Zero when $a and $b have identical sort orders.
* Positive when $b comes before $a.
*
* @return int
* Negative when $a comes before $b.Zero when $a and $b have identical sort
* orders. Positive when $b comes before $a.
*/
public static function compareBooksBySortOrder($a, $b) {
$weightDiff = $a->weight - $b->weight;
......@@ -53,8 +55,8 @@ class Library {
}
/**
* @return array Book data in 2-dimensional array format.
* Used for the docs:list command.
* @return array
* Book data in 2-dimensional array format. Used for the docs:list command.
*
* Each item in the array contains keys:
* - book: string (ex: 'dev')
......@@ -84,7 +86,8 @@ class Library {
/**
* Selects one of the many books within the library
*
* @param string $slug The short name describing the book
* @param string $slug
* The short name describing the book
*
* @return Book
*/
......@@ -104,7 +107,8 @@ class Library {
*
* @param string $category
*
* @return array of Book objects
* @return array
* Array of Book objects (without keys)
*/
public function getBooksByCategory($category) {
$books = array();
......@@ -121,14 +125,17 @@ class Library {
*
* @param string $repoURL
*
* @return array of strings to identify each occurence of a book/language
* which matches the specified repository. Example return:
* ["mybook/en", "mybook/es"]
* Note that it's rare for a repository to map to multiple
* identifiers. In most cases the return will be an array with
* a single element.
* Note also that the return identifier only has the book slug
* and the language code, not the branch name.
* @return array
* Array of strings to identify each occurrence of a book/language
* which matches the specified repository.
*
* e.g. ["mybook/en", "mybook/es"]
*
* Note that it's rare for a repository to map to multiple identifiers.
* In most cases the return will be an array with a single element.
*
* Note also that the return identifier only has the book slug and the
* language code, not the branch name.
*/
public function getIdentifiersByRepo($repoURL) {
$identifiers = array();
......@@ -145,10 +152,25 @@ class Library {
/**
* Parses an identifier into components we can use to identify a book
*
* @param string $identifier (e.g. "user/en/master", "user/en", "user", "")
* See LibraryTest::identifierProvider() for examples
*
* @return array See LibraryTest::identifierProvider() for examples
*/
* @param string $identifier
* examples: "user/en/master", "user/en", "user", ""
*
* @return array
* example:
* [
* 'bookSlug' => 'dev',
* 'languageCode' => 'en',
* 'versionDescriptor' => 'latest',
* 'editionIdentifier' => 'dev/en/latest',
* 'path' => 'category/foo/my-page',
* 'fragment' => 'some-section',
* ]
*
* The array will aways have the keys shown above, but values will be NULL
* if those components do not exist in the given identifier
*/
public static function parseIdentifier($identifier) {
// Remove junk chars from both ends
$identifier = trim($identifier, "/# \t\n\r\0\x0B");
......
......@@ -7,28 +7,28 @@ use AppBundle\Utils\StringTools;
class Version {
/**
* @var string Version name (e.g. "4.6" or "latest"). This is what
* readers see. Sometimes it's the same as name of the
* branch, but not always. It can contain pretty much whatever
* characters you want.
* @var string
* Version name (e.g. "4.6" or "latest"). This is what readers see.
* Sometimes it's the same as name of the branch, but not always. It can
* contain pretty much whatever characters you want.
*/
public $name;
/**
* @var string The git branch that corresponds to this version
* (e.g. "master" or "4.6"). Sometimes it's the same as
* $name but not always. It can be any string that actually
* maps to a real git branch, including strings with forward
* slashes.
* @var string
* The git branch that corresponds to this version (e.g. "master" or "4.6").
* Sometimes it's the same as $name but not always. It can be any string
* that actually maps to a real git branch, including strings with forward
* slashes.
*/
public $branch;
/**
* @var array An array (without keys) of strings which represent
* aliases to this version of the book. For each alias,
* we will create symbolic links so that a reader can also
* access this version of the book at a URL with that
* alias.
* @var array
* An array (without keys) of strings which represent aliases to this
* version of the book. For each alias, we will create symbolic links so
* that a reader can also access this version of the book at a URL with that
* alias.
*/
public $aliases;
......@@ -47,10 +47,15 @@ class Version {
* If the constructor receives different $name and $branch values, it will
* automatically add an alias for $name.
*
* @param string $name (e.g. "latest", "master", "4.7", etc.)
* @param string $branch (e.g "master", "4.7", etc)
* @param array $aliases Array of strings containing names which can also be
* used to reference this version.
* @param string $name
* e.g. "latest", "master", "4.7"
*
* @param string $branch
* e.g "master", "4.7"
*
* @param array $aliases
* Array of strings containing names which can also be used to reference
* this version.
*/
public function __construct($name, $branch = NULL, $aliases = array()) {
$this->name = $name;
......@@ -58,6 +63,10 @@ class Version {
$this->setupAliases($aliases);
}
/**
* @param $aliases array|string
* e.g. "latest"
*/
private function setupAliases($aliases) {
// wrap $aliases in array, if necessary
if (!is_array($aliases)) {
......@@ -84,7 +93,8 @@ class Version {
* Gives an array of all unique strings that can be used to describe this
* version, including branch, name, and any aliases.
*
* @return array of strings (without keys)
* @return array
* Array of strings (without keys)
*/
public function allDescriptors() {
$result = $this->aliases;
......@@ -99,7 +109,8 @@ class Version {
*
* If validation succeeds, this function returns nothing
*
* If validation fails, this function throws an exception.
* @throws \Exception
* If validation fails
*/
public function validate() {
if (preg_match("#/#", $this->branch)) {
......
......@@ -20,16 +20,22 @@ class GitHubHookProcessor {
public $branch;
/**
*
* Constructor
*/
public function __construct() {
}
/**
* Process a GitHub webhook
*
* @param string $event
* e.g. 'pull_request', 'push'
*
* @param string $event (e.g. 'pull_request', 'push')
* @param mixed $payload An object given by json_decode()
* @param mixed $payload
* An object given by json_decode()
*
* @throws \Exception
*/
public function process($event, $payload) {
if (empty($payload)) {
......@@ -49,7 +55,10 @@ class GitHubHookProcessor {
* Use a "push" event to figure out what branch and repo we are talking
* about, and the also work out what emails we should send.
*
* @param mixed $payload An object given by json_decode()
* @param mixed $payload
* An object given by json_decode()
*
* @throws \Exception
*/
public function getDetailsFromPush($payload) {
$this->branch = preg_replace("#.*/(.*)#", "$1", $payload->ref);
......@@ -70,7 +79,8 @@ class GitHubHookProcessor {
* Adds one or more email recipients, and makes sure all recipients are
* kept unique
*
* @param array $recipients Array of strings for emails of people to notify
* @param array $recipients
* Array of strings for emails of people to notify
*/
public function addRecipients($recipients) {
if (!is_array($recipients)) {
......
......@@ -17,8 +17,11 @@ class LocaleTools {
* $languageCode = 'en' and $localeCode = 'es' this function would answer the
* question "what word do Spanish-speaking people use to refer to English?"
*
* @param string $languageCode The language we're asking about
* @param string $localeCode The language in which we want our answer
* @param string $languageCode
* The language we're asking about
*
* @param string $localeCode
* The language in which we want our answer
*
* @return string
*/
......@@ -31,8 +34,11 @@ class LocaleTools {
/**
* Checks to see whether a given language code is a valid ISO-639-1 code.
*
* @param string $languageCode (e.g. "en", or "es")
* @return boolean TRUE if the code is valid
* @param string $languageCode
* e.g. "en", or "es"
*
* @return boolean
* TRUE if the code is valid
*/
public static function codeIsValid($languageCode) {
return file_exists(self::LOCALES_DIR . "/$languageCode.json");
......
......@@ -21,22 +21,24 @@ class MkDocs {
private $fileLocator;
/**
* @var string The full filesystem path to the directory containing the
* markdown files
* @var string
* The full filesystem path to the directory containing the markdown files
*/
private $sourcePath;
/**
* @var string $destinationPath The full filesystem path to the directory
* where we want the published content to go
* @var string $destinationPath
* The full filesystem path to the directory where we want the published
* content to go
*/
private $destinationPath;
/**
* @var string The full filesystem path to the directory which stores
* different possible theme customizations. Within this directory,
* separate directories should exist, per theme, for the
* customizations, named with the same name as the theme.
* @var string
* The full filesystem path to the directory which stores different
* possible theme customizations. Within this directory, separate
* directories should exist, per theme, for the customizations, named with
* the same name as the theme.
*/
private $themeCustomPathRoot;
......@@ -46,20 +48,23 @@ class MkDocs {
private $themeCustomPath;
/**
* @var array A associative array with config values to put in the 'extra'
* setting when building the book
* @var array
* A associative array with config values to put in the 'extra' setting
* when building the book
*/
private $extraConfig;
/**
* @var string The full filesystem location of the mkdocs.yml config file to
* use when building the book. This is the file as it's stored
* after adjustments we make to it.
* @var string
* The full filesystem location of the mkdocs.yml config file to use when
* building the book. This is the file as it's stored after adjustments we
* make to it.
*/
private $configFile;
/**
* @param Filesystem $fs
*
* @param FileLocator $fileLocator
*/
public function __construct(Filesystem $fs, FileLocator $fileLocator) {
......@@ -135,14 +140,19 @@ class MkDocs {
/**
* Run MkDocs to build a book
*
* @param string $sourcePath The full filesystem path to the directory
* containing the markdown files
* @param string $sourcePath
* The full filesystem path to the directory containing the markdown files
*
* @param string $destinationPath
* The full filesystem path to the directory where we want the published
* content to go
*
* @param string $destinationPath The full filesystem path to the directory
* where we want the published content to go
* @param array $extraConfig
* A associative array with config values to put in the 'extra' setting
* when building the book
*
* @param array $extraConfig A associative array with config values to put in
* the 'extra' setting when building the book
* @throws \Exception
* If build process fails
*/
public function build($sourcePath, $destinationPath, $extraConfig = array()) {
$this->sourcePath = $sourcePath;
......
......@@ -36,8 +36,9 @@ class Publisher {
public $logger;
/**
* @var array Messages with key as a string to represent message type and
* value as a string with the message content
* @var array
* Messages with key as a string to represent message type and value as a
* string with the message content
*/
public $messages = array();
......@@ -65,8 +66,9 @@ class Publisher {
/**
*
* @var string The full URL of the published book
* (e.g. "https://docs.civicrm.org/user/en/latest")
* @var string
* The full URL of the published book
* e.g. "https://docs.civicrm.org/user/en/latest"
*/
public $publishURLFull;
......@@ -76,14 +78,15 @@ class Publisher {
public $publishPathRoot;
/**
* @var string The full filesystem path to the directory where the book
* is to be published
* @var string
* The full filesystem path to the directory where the book is to be
* published
*/
public $publishPath;
/**
* @var string The filesystem path to the directory containing all the
* git repositories.
* @var string
* The filesystem path to the directory containing all the git repositories.
*/
public $repoPathRoot;
......@@ -98,7 +101,7 @@ class Publisher {
public $version;
/**
* @var string the URL of the repository (e.g. https://github.com/foo/bar
* @var string the URL of the repository e.g. https://github.com/foo/bar
*/
public $repoURL;
......@@ -116,6 +119,7 @@ class Publisher {
* @param string $reposPathRoot
* @param string $publishPathRoot
* @param \AppBundle\Utils\MkDocs $mkDocs
* @throws \Exception
*/
public function __construct(
$requestStack,
......@@ -425,14 +429,14 @@ class Publisher {
/**
* Publish a book, or multiple books, based on a flexible identifier
*
* @param string $identifier A string describing the book, or books. For
* example, "user/en/latest" will publish one
* version of one language of one book, or "user"
* will publish all lanugages and all versions
* within the book "user".
* @param string $identifier
* A string describing the book, or books. For example "user/en/latest" will
* publish one version of one language of one book, or "user" will publish
* all lanugages and all versions within the book "user".
*
* @return bool TRUE if all books were published, FALSE if there were any
* errors while publishing any of the books
* @return bool
* TRUE if all books were published, FALSE if there were any errors while
* publishing any of the books
*/
public function publish($identifier = "") {
$this->suppliedIdentifier = $identifier;
......@@ -464,10 +468,12 @@ class Publisher {
/**
* Publishes all the things!
*
* All the versions of all the languages of all the books
*
* @return bool TRUE if all books were published, FALSE if there were any
* errors while publishing any of the books