added inline docs

src/Inline/Parser/CodepenParser.php

@@ -21,9 +21,12 @@ public function parse(InlineParserContext $inlineContext)
 
         $cursor->advance();
 
+        //check that the given user input is a valid codepen url
+        //and the required `codepen:` prefix exists
         $regex = '/^(?:codepen)\s(https:\/\/codepen\.io\/([^\/]+\/)?([a-zA-Z0-9]+)\/pen\/([a-zA-Z0-9]+)?)/';
         $validate = $cursor->match($regex);
 
+        //the computer says no
         if (!$validate) {
             $cursor->restoreState($savedState);
 
@@ -32,7 +35,8 @@ public function parse(InlineParserContext $inlineContext)
 
         $matches = [];
         preg_match($regex, $validate, $matches);
-
+
+        //return the given codepen url to the renderer class
         $inlineContext->getContainer()->appendChild(new Codepen($matches[1]));
 
         return true;

src/Inline/Parser/GistParser.php

@@ -21,9 +21,12 @@ public function parse(InlineParserContext $inlineContext)
 
         $cursor->advance();
 
+        //check that the given user input is a valid gist url
+        //and the required `gist:` prefix exists
         $regex = '/^(?:gist)\s(https:\/\/gist.github.com\/([^\/]+\/)?([a-zA-Z0-9]+)\/([a-zA-Z0-9]+)?)/';
         $validate = $cursor->match($regex);
 
+        //the computer says no
         if (!$validate) {
             $cursor->restoreState($savedState);
 
@@ -33,6 +36,7 @@ public function parse(InlineParserContext $inlineContext)
         $matches = [];
         preg_match($regex, $validate, $matches);
 
+        //return the given gist url to the renderer class
         $inlineContext->getContainer()->appendChild(new Gist($matches[1]));
 
         return true;

src/Inline/Parser/SoundCloudParser.php

@@ -21,9 +21,12 @@ public function parse(InlineParserContext $inlineContext)
 
         $cursor->advance();
 
+        //check that the given user input is a valid soundcloud url
+        //and the required `soundcloud:` or `:sc` prefix exists
         $regex = '/^(?:soundcloud|sc)\s((?:https?\:\/\/)?(?:www\.)?(?:soundcloud\.com\/)[^&#\s\?]+\/[^&#\s\?]+)/';
         $validate = $cursor->match($regex);
 
+        //the computer says no
         if (!$validate) {
             $cursor->restoreState($savedState);
 

src/Inline/Parser/YouTubeParser.php

@@ -21,9 +21,12 @@ public function parse(InlineParserContext $inlineContext)
 
         $cursor->advance();
 
+        //regex to ensure that we got a valid youtube url
+        //and the required `youtube:` prefix exists
         $regex = '/^(?:youtube)\s(?:https?\:\/\/)?(?:www\.)?(?:youtube\.com\/watch\?v=|youtu\.be\/)([^&#\s\?]+)(?:\?.[^\s]+)?/';
         $validate = $cursor->match($regex);
 
+        //the computer says no
         if (!$validate) {
             $cursor->restoreState($savedState);
 
@@ -34,6 +37,7 @@ public function parse(InlineParserContext $inlineContext)
         preg_match($regex, $validate, $matches);
         $videoId = $matches[1];
 
+        //generates a valid youtube embed url with the parsed video id from the given url
         $inlineContext->getContainer()->appendChild(new YouTube("https://www.youtube.com/embed/$videoId"));
 
         return true;

src/Inline/Renderer/CodepenRenderer.php

@@ -36,12 +36,16 @@ public function render(AbstractInline $inline, ElementRendererInterface $htmlRen
 
         $apiResponse = $this->getContent($apiUrl);
 
+        //seems that the used codepen url is invalid
+        //or codepen is currently not available
         if (is_null($apiResponse)) {
             throw new \ErrorException('Codepen request returned null: ' . $apiUrl);
         }
 
+        //parse the oembed response
         $embed = json_decode($apiResponse);
 
+        //return the oembed html snippet with a div as wrapper element
         return new HtmlElement('div', ['class' => 'codepen-container'], $embed->html);
     }
 

src/Inline/Renderer/GistRenderer.php

@@ -30,10 +30,13 @@ public function render(AbstractInline $inline, ElementRendererInterface $htmlRen
             throw new \InvalidArgumentException('Incompatible inline type: ' . get_class($inline));
         }
 
+        //generates the same script element, which you can see
+        //in the "embed gist" input field
         $script = new HtmlElement('script', [
             'src' => $inline->getUrl().'.js'
         ]);
 
+        //add a div wrapper around the script element
         return new HtmlElement('div', ['class' => 'gist-container'], $script);
     }
 

src/Inline/Renderer/SoundCloudRenderer.php

@@ -35,12 +35,16 @@ public function render(AbstractInline $inline, ElementRendererInterface $htmlRen
         $url = "https://soundcloud.com/oembed?&format=json&url={$inline->getUrl()}&maxheight=166";
         $soundCloud = $this->getContent($url);
 
+        //seems that the used soundcloud url is invalid
+        //or soundcloud is currently not available
         if (is_null($soundCloud)) {
             throw new \ErrorException('SoundCloud request returned null: ' . $url);
         }
 
+        //parse the oembed response
         $soundCloud = json_decode($soundCloud);
 
+        //use the oembed html snippet as response 
         return $soundCloud->html;
     }
 

src/Inline/Renderer/YouTubeRenderer.php

@@ -30,6 +30,7 @@ public function render(AbstractInline $inline, ElementRendererInterface $htmlRen
             throw new \InvalidArgumentException('Incompatible inline type: ' . get_class($inline));
         }
 
+        //create a new iframe with the given youtube url
         $iframe = new HtmlElement('iframe', [
             'width' => 640,
             'height' => 390,
@@ -38,6 +39,7 @@ public function render(AbstractInline $inline, ElementRendererInterface $htmlRen
             'frameborder' => 0,
         ]);
 
+        //return the iframe with a span as wrapper element
         return new HtmlElement('span', ['class' => 'youtube-video'], $iframe);
     }