Issue CollaboraOnline#43: Write meaningful doc comments.

phpcs.xml

@@ -26,13 +26,6 @@
     <exclude name="Drupal.NamingConventions.ValidVariableName.LowerCamelName"/>
     <exclude name="Drupal.NamingConventions.ValidFunctionName.ScopeNotCamelCaps"/>
 
-    <!-- Fix doc comments later. -->
-    <exclude name="Drupal.Commenting.ClassComment"/>
-    <exclude name="Drupal.Commenting.DataTypeNamespace"/>
-    <exclude name="Drupal.Commenting.DocComment"/>
-    <exclude name="Drupal.Commenting.FunctionComment"/>
-    <exclude name="Drupal.Commenting.VariableComment"/>
-
     <!-- Fix translatable strings later. -->
     <exclude name="Drupal.Semantics.FunctionT.WhiteSpace"/>
   </rule>

src/Controller/ViewerController.php

@@ -24,10 +24,18 @@
  */
 class ViewerController extends ControllerBase {
 
+    /**
+     * The renderer service.
+     *
+     * @var \Drupal\Core\Render\RendererInterface
+     */
     private $renderer;
 
     /**
      * The controller constructor.
+     *
+     * @param \Drupal\Core\Render\RendererInterface $renderer
+     *   The renderer service.
      */
     public function __construct(RendererInterface $renderer) {
         $this->renderer = $renderer;
@@ -45,9 +53,14 @@ public static function create(ContainerInterface $container): self {
     /**
      * Returns a raw page for the iframe embed.
      *
-     * Set edit to true for an editor.
+     * @param \Drupal\media\Entity\Media $media
+     *   Media entity.
+     * @param bool $edit
+     *   TRUE to open Collabora Online in edit mode.
+     *   FALSE to open Collabora Online in readonly mode.
      *
-     * @return Response
+     * @return \Symfony\Component\HttpFoundation\Response
+     *   Response suitable for iframe, without the usual page decorations.
      */
     public function editor(Media $media, $edit = FALSE) {
         $options = [

src/Controller/WopiController.php

@@ -40,6 +40,17 @@ public static function permissionDenied(): Response {
         );
     }
 
+    /**
+     * Handles the WOPI 'info' request for a media entity.
+     *
+     * @param string $id
+     *   Media id from url.
+     * @param \Symfony\Component\HttpFoundation\Request $request
+     *   Request object with query parameters.
+     *
+     * @return \Symfony\Component\HttpFoundation\Response
+     *   The response with file contents.
+     */
     public function wopiCheckFileInfo(string $id, Request $request) {
         $token = $request->query->get('access_token');
 
@@ -97,6 +108,17 @@ public function wopiCheckFileInfo(string $id, Request $request) {
         return $response;
     }
 
+    /**
+     * Handles the wopi "content" request for a media entity.
+     *
+     * @param string $id
+     *   Media id from url.
+     * @param \Symfony\Component\HttpFoundation\Request $request
+     *   Request object with query parameters.
+     *
+     * @return \Symfony\Component\HttpFoundation\Response
+     *   The response with file contents.
+     */
     public function wopiGetFile(string $id, Request $request) {
         $token = $request->query->get('access_token');
 
@@ -121,6 +143,17 @@ public function wopiGetFile(string $id, Request $request) {
         return $response;
     }
 
+    /**
+     * Handles the wopi "save" request for a media entity..
+     *
+     * @param string $id
+     *   Media id from url.
+     * @param \Symfony\Component\HttpFoundation\Request $request
+     *   Request object with headers, query parameters and payload.
+     *
+     * @return \Symfony\Component\HttpFoundation\Response
+     *   The response.
+     */
     public function wopiPutFile(string $id, Request $request) {
         $token = $request->query->get('access_token');
         $timestamp = $request->headers->get('x-cool-wopi-timestamp');
@@ -214,11 +247,15 @@ public function wopiPutFile(string $id, Request $request) {
     /**
      * The WOPI entry point.
      *
-     * action: 'info', 'content' or 'save'.
-     * id: the ID of the media.
-     * request: The request as originating.
+     * @param string $action
+     *   One of 'info', 'content' or 'save', depending with path is visited.
+     * @param string $id
+     *   Media id from url.
+     * @param \Symfony\Component\HttpFoundation\Request $request
+     *   Request object for headers and query parameters.
      *
-     * @return Response
+     * @return \Symfony\Component\HttpFoundation\Response
+     *   Response to be consumed by Collabora Online.
      */
     public function wopi(string $action, string $id, Request $request) {
         $returnCode = Response::HTTP_BAD_REQUEST;

src/Cool/CoolRequest.php

@@ -13,9 +13,13 @@
 namespace Drupal\collabora_online\Cool;
 
 /**
- * Get the discovery XML content
+ * Gets the contents of discovery.xml from the Collabora server.
  *
- * Return `false` in case of error.
+ * @param string $server
+ *   Url of the Collabora Online server.
+ *
+ * @return string|false
+ *   The full contents of discovery.xml, or FALSE on failure.
  */
 function getDiscovery($server) {
     $discovery_url = $server . '/hosting/discovery';
@@ -36,6 +40,19 @@ function getDiscovery($server) {
     return $res;
 }
 
+/**
+ * Extracts a WOPI url from the parsed discovery.xml.
+ *
+ * @param \SimpleXMLElement|null|false $discovery_parsed
+ *   Parsed contents from discovery.xml from the Collabora server.
+ *   Currently, NULL or FALSE are supported too, but lead to NULL return value.
+ * @param string $mimetype
+ *   MIME type for which to fetch the WOPI url. E.g. 'text/plain'.
+ *
+ * @return mixed|null
+ *   WOPI url as configured for this MIME type in discovery.xml, or NULL if none
+ *   was found for the given MIME type.
+ */
 function getWopiSrcUrl($discovery_parsed, $mimetype) {
     if ($discovery_parsed === NULL || $discovery_parsed == FALSE) {
         return NULL;
@@ -47,13 +64,34 @@ function getWopiSrcUrl($discovery_parsed, $mimetype) {
     return NULL;
 }
 
+/**
+ * Checks if a string starts with another string.
+ *
+ * @param string $s
+ *   Haystack.
+ * @param string $ss
+ *   Needle.
+ *
+ * @return bool
+ *   TRUE if $ss is a prefix of $s.
+ *
+ * @see str_starts_with()
+ */
 function strStartsWith($s, $ss) {
     $res = strrpos($s, $ss);
     return !is_bool($res) && $res == 0;
 }
 
+/**
+ * Helper class to fetch a WOPI client url.
+ */
 class CoolRequest {
 
+    /**
+     * Error code from last attempt to fetch the client WOPI url.
+     *
+     * @var int
+     */
     private $error_code;
 
     const ERROR_MSG = [
@@ -67,18 +105,37 @@ class CoolRequest {
         204 => 'Warning! You have to specify the scheme protocol too (http|https) for the server address.',
     ];
 
+    /**
+     * The WOPI url that was last fetched, or '' as initial value.
+     *
+     * @var int
+     */
     private $wopi_src;
 
+    /**
+     * Constructor.
+     */
     public function __construct() {
         $this->error_code = 0;
         $this->wopi_src = '';
     }
 
+    /**
+     * Gets an error string from the last attempt to fetch the WOPI url.
+     *
+     * @return string
+     *   Error string containing int error code and a message.
+     */
     public function errorString() {
         return $this->error_code . ': ' . static::ERROR_MSG[$this->error_code];
     }
 
-    /** Return the wopi client URL */
+    /**
+     * Gets the URL for the WOPI client.
+     *
+     * @return string|null
+     *   The WOPI client url, or NULL on failure.
+     */
     public function getWopiClientURL() {
         $_HOST_SCHEME = isset($_SERVER['HTTPS']) ? 'https' : 'http';
         $default_config = \Drupal::config('collabora_online.settings');