Added comments

Added comments for readability and maintainability of the code.

Author: QuickWrite

includes/MultiCodeBlock.php

@@ -10,6 +10,11 @@
 
 require_once 'highlight/Highlighter.php';
 
+/**
+ * The main class for the MultiCodeBlock MediaWiki-Extension.
+ * 
+ * @author QuickWrite
+ */
 class MultiCodeBlock {
 	public static function onParserFirstCallInit( Parser &$parser ) {
 		$parser->setHook( 'multicodeblock', [ self::class, 'renderMultiCodeBlock' ] );
@@ -20,6 +25,14 @@ public static function onBeforePageDisplay( OutputPage &$out ) {
 		$out->addModules( [ 'ext.multicodeblock.js' ] );
 	}
 
+	/**
+	 * Returns a string based on the MultiCodeBlock HTML-Element
+	 * 
+	 * @param string $input The content of the MultiCodeBlock HTML-Element
+	 * @param array $args The arguments of the MultiCodeBlock HTML-Element
+	 * @param Parser $parser The MediaWiki syntax parser
+	 * @param PPFrame $frame MediaWiki frame
+	 */
 	public static function renderMultiCodeBlock( $input, array $args, Parser $parser, PPFrame $frame ) {
 		$code = findCodeBlocks($input);
 

includes/highlight/Code.php

@@ -1,13 +1,29 @@
 <?php
 
+/**
+ * Saves the code and the language as well as highlights the code.
+ * 
+ * @author QuickWrite
+ * @global string $code The code stored in raw text format.
+ * @global string $lang The language that was inputted.
+ * 
+ * @param string $code The code that should be highlighted.
+ * @param string $lang The language the code should be highlighted in.
+ */
 class Code {
     public $code;
     public $lang;
-
+    
     public function __construct(&$code, $lang) {
         $this->setCode($code, $lang);
     }
 
+    /**
+     * Returns a highlighted version of the code.
+     * 
+     * @param Highlighter $h1 The highlighter class og Highlight.php to highlight the code.
+     * @return string The highlighted version the the $code.
+     */
     public function &highlight(\Highlight\Highlighter &$hl) {
         $highlighted;
 
@@ -20,6 +36,12 @@ public function &highlight(\Highlight\Highlighter &$hl) {
         return $highlighted;
     }
 
+    /**
+     * Inserts the code into the attributes.
+     * 
+     * @param string $code The code that should be inserted into the class
+     * @param string $lang The language the code is written in.
+     */
     public function setCode($code, $lang) {
         $this->code = $code;
         $this->lang = $lang;

includes/highlight/CustomOptions.php

@@ -1,6 +1,11 @@
 <?php
 require_once __DIR__ . '/../vendor/autoload.php';
 
+/**
+ * Returns specific options for the HTML-Parser. 
+ * 
+ * @return \PHPHtmlParser\Options The options as a PHPHtmlParser class.
+ */
 function getOptions() {
     $options = new \PHPHtmlParser\Options();
     $options->setPreserveLineBreaks(true);

includes/highlight/Description.php

@@ -4,6 +4,16 @@
 
 use PHPHtmlParser\Dom;
 
+/**
+ * Stores the description of the code.
+ * 
+ * @author QuickWrite
+ * 
+ * @global array $texts An array of all the different descriptions.
+ * @global array $keys The lines where the descriptions should start.
+ * 
+ * @param string $dom A string that has the content of the <desc>-element.
+ */
 class Description {
     public $texts = array();
     public $keys = array();
@@ -19,13 +29,25 @@ public function __construct($dom = null) {
         $this->setTexts($dom);
     }
 
+    /**
+     * Returns the last line the current description.
+     * 
+     * @param int $index The index of the textblock.
+     * 
+     * @return int The last line of the textblock (based on $index).
+     */
     public function getNext($index) {
         if($index + 1 > sizeof($this->keys))
             return null;
 
         return $this->keys[$index] - 1;
     }
 
+    /**
+     * Inserts the description into the attrributes.
+     * 
+     * @param string $dom A string that has the content of the <desc>-element.
+     */
     public function setTexts(&$dom) {
 
         $content = new Dom();

includes/highlight/Highlighter.php

@@ -7,14 +7,29 @@
 
 use PHPHtmlParser\Dom;
 
+/**
+ * Returns the DOM-Parser with custom options and the HTML-Tree
+ * 
+ * @param string $content The content that should be parsed by the DOM-Parser
+ * 
+ * @return PHPHtmlParser\Dom The DOM-Element that has the HTML-Tree
+ */
 function getDOM(&$content) {
     $dom = new Dom();
     $dom->loadStr($content, getOptions());
 
     return $dom;
 }
 
-function createFrame($lang, &$code) {
+/**
+ * Returns the MultiCodeBlock as a whole.
+ * 
+ * @param array $lang All of the languages of the different codeblocks.
+ * @param string $code The codeblocks as a whole.
+ * 
+ * @return string The whole MultiCodeBlock.
+ */
+function createFrame(array $lang, string &$code) {
     $size = sizeof($lang);
     $copyIcon = '<svg xmlns="http://www.w3.org/2000/svg" height="24px" viewBox="0 0 24 24" width="24px" fill="#000000"><path d="M0 0h24v24H0z" fill="none"/><path d="M16 1H4c-1.1 0-2 .9-2 2v14h2V3h12V1zm3 4H8c-1.1 0-2 .9-2 2v14c0 1.1.9 2 2 2h11c1.1 0 2-.9 2-2V7c0-1.1-.9-2-2-2zm0 16H8V7h11v14z"/></svg>';
 
@@ -32,13 +47,31 @@ function createFrame($lang, &$code) {
     return $return;
 }
 
-function replaceLang($lang) {
+/**
+ * Returns a human-readable-version of the language.
+ * 
+ * @param string $lang The specific language token
+ * 
+ * @return string The replaced language.
+ */
+function replaceLang(string $lang) {
     $file = file_get_contents(__DIR__ . '/languages/languages.json');
     $languages = json_decode($file, true);
 
     return $languages[$lang];
 }
 
+/**
+ * Returns a single codeblock
+ * 
+ * @param DOMElement $codevariant The content of the `<codevariant>` element.
+ * @param string $code The code inside the `<codevariant>` block.
+ * @param DOMElement $description The content of the `<desc>` element.
+ * @param Parser $parser The parser object by MediaWiki
+ * @param Highlighter $h1 The highlighter object
+ * 
+ * @return array The codeblock as the first element and the language as the second element.
+ */
 function createCodeBlock(&$codevariant, &$code, &$description, Parser &$parser, \Highlight\Highlighter &$h1) {
 
     $lang = $codevariant->getAttribute("lang");
@@ -60,7 +93,16 @@ function createCodeBlock(&$codevariant, &$code, &$description, Parser &$parser,
     return array(combineCodeDescription(($isObject ? $highlight->value : $highlight), $desc, $parser), ($isObject ? replaceLang($highlight->language) : $lang));
 }
 
-function combineCodeDescription($code, Description &$desc, Parser &$parser) {
+/**
+ * Returns the combined version of the code and the description.
+ * 
+ * @param string $code The code inside the `<code>` element
+ * @param Description $desc The description as a Description object
+ * @param Parser $parser The parser object by MediaWiki
+ * 
+ * @return string A combined version of the code and the description with the MediaWiki syntax.
+ */
+function combineCodeDescription(string $code, Description &$desc, Parser &$parser) {
     $arr = explode("\n", $code);
     $size = sizeof($arr);
 
@@ -99,7 +141,14 @@ function combineCodeDescription($code, Description &$desc, Parser &$parser) {
     return $return;
 }
 
-function findCodeBlocks(&$codeblock) {
+/**
+ * Returns the code in the `<code>` tags.
+ * 
+ * @param string $codeblock The object where all of the codeblocks should be removed.
+ * 
+ * @return array An array of the code.
+ */
+function findCodeBlocks(string &$codeblock) {
     preg_match_all("(< *code *>((.|\n)*?)<\/code *>)", $codeblock, $array);
 
     return $array[1];