Issue #3048081 by Pancho: Properly document all FillPdfActionPlugins

src/Plugin/FillPdfActionPlugin/FillPdfDownloadAction.php

@@ -2,14 +2,13 @@
 
 namespace Drupal\fillpdf\Plugin\FillPdfActionPlugin;
 
-use Drupal\Core\Annotation\Translation;
-use Drupal\fillpdf\Annotation\FillPdfActionPlugin;
 use Drupal\fillpdf\Plugin\FillPdfActionPluginBase;
 use Symfony\Component\HttpFoundation\Response;
 use Symfony\Component\HttpFoundation\ResponseHeaderBag;
 
 /**
- * Class FillPdfDownloadAction
+ * Action plugin sending a generated PDF file to the users browser.
+ *
  * @package Drupal\fillpdf\Plugin\FillPdfActionPlugin
  *
  * @FillPdfActionPlugin(
@@ -19,6 +18,14 @@ use Symfony\Component\HttpFoundation\ResponseHeaderBag;
  */
 class FillPdfDownloadAction extends FillPdfActionPluginBase {
 
+  /**
+   * Executes this plugin.
+   *
+   * Sends the PDF file to the user's browser.
+   *
+   * @return \Symfony\Component\HttpFoundation\Response
+   *   Sends the PDF file to the browser.
+   */
   public function execute() {
     $response = new Response($this->configuration['data']);
 

src/Plugin/FillPdfActionPlugin/FillPdfRedirectAction.php

@@ -2,12 +2,11 @@
 
 namespace Drupal\fillpdf\Plugin\FillPdfActionPlugin;
 
-use Drupal\Core\Annotation\Translation;
-use Drupal\fillpdf\Annotation\FillPdfActionPlugin;
 use Symfony\Component\HttpFoundation\RedirectResponse;
 
 /**
- * Class FillPdfRedirectAction
+ * Action plugin redirecting to a generated PDF file saved to the filesystem.
+ *
  * @package Drupal\fillpdf\Plugin\FillPdfActionPlugin
  *
  * @FillPdfActionPlugin(
@@ -17,6 +16,14 @@ use Symfony\Component\HttpFoundation\RedirectResponse;
  */
 class FillPdfRedirectAction extends FillPdfSaveAction {
 
+  /**
+   * Executes this plugin.
+   *
+   * Saves the PDF file to the filesystem and redirects to it.
+   *
+   * @return \Symfony\Component\HttpFoundation\RedirectResponse
+   *   Redirects user to the generated PDF file.
+   */
   public function execute() {
     $saved_file = $this->savePdf();
 

src/Plugin/FillPdfActionPlugin/FillPdfSaveAction.php

@@ -2,15 +2,14 @@
 
 namespace Drupal\fillpdf\Plugin\FillPdfActionPlugin;
 
-use Drupal\Core\Annotation\Translation;
-use Drupal\fillpdf\Annotation\FillPdfActionPlugin;
 use Drupal\fillpdf\OutputHandler;
 use Drupal\fillpdf\Plugin\FillPdfActionPluginBase;
 use Symfony\Component\DependencyInjection\ContainerInterface;
 use Symfony\Component\HttpFoundation\RedirectResponse;
 
 /**
- * Class FillPdfSaveAction
+ * Action plugin saving a generated PDF file to the filesystem.
+ *
  * @package Drupal\fillpdf\Plugin\FillPdfActionPlugin
  *
  * @FillPdfActionPlugin(
@@ -20,19 +19,51 @@ use Symfony\Component\HttpFoundation\RedirectResponse;
  */
 class FillPdfSaveAction extends FillPdfActionPluginBase {
 
-  /** @var OutputHandler $outputHandler */
+  /**
+   * The FillPdf output handler.
+   *
+   * @var \Drupal\fillpdf\OutputHandler
+   */
   protected $outputHandler;
 
+  /**
+   * Constructs a \Drupal\Component\Plugin\PluginBase object.
+   *
+   * @param \Drupal\fillpdf\OutputHandler $output_handler
+   *   The FillPdf output handler.
+   * @param array $configuration
+   *   A configuration array containing information about the plugin instance.
+   * @param string $plugin_id
+   *   The plugin_id for the plugin instance.
+   * @param mixed $plugin_definition
+   *   The plugin implementation definition.
+   */
   public function __construct(OutputHandler $output_handler, array $configuration, $plugin_id, $plugin_definition) {
     $this->outputHandler = $output_handler;
 
     parent::__construct($configuration, $plugin_id, $plugin_definition);
   }
 
+  /**
+   * {@inheritdoc}
+   */
   public static function create(ContainerInterface $container, array $configuration, $plugin_id, $plugin_definition) {
-    return new static($container->get('fillpdf.output_handler'), $configuration, $plugin_id, $plugin_definition);
+    return new static(
+      $container->get('fillpdf.output_handler'),
+      $configuration,
+      $plugin_id,
+      $plugin_definition
+    );
   }
 
+  /**
+   * Executes this plugin.
+   *
+   * Saves the PDF file to the filesystem and redirects to the front page.
+   *
+   * @return \Symfony\Component\HttpFoundation\RedirectResponse
+   *   Redirects user to the front page.
+   */
   public function execute() {
     $this->savePdf();
 
@@ -41,6 +72,14 @@ class FillPdfSaveAction extends FillPdfActionPluginBase {
     return $response;
   }
 
+  /**
+   * Saves merged PDF data to the filesystem.
+   *
+   * @return \Drupal\file\FileInterface|false
+   *   The saved file entity, or FALSE on error.
+   *
+   * @see \Drupal\fillpdf\OutputHandlerInterface::savePdfToFile()
+   */
   protected function savePdf() {
     // @todo: Error handling?
     return $this->outputHandler->savePdfToFile($this->configuration);

src/Plugin/FillPdfActionPluginBase.php

@@ -10,26 +10,37 @@ use Symfony\Component\DependencyInjection\ContainerInterface;
  */
 abstract class FillPdfActionPluginBase extends PluginBase implements FillPdfActionPluginInterface {
 
-  public function __construct(array $configuration, $plugin_id, $plugin_definition) {
-    parent::__construct($configuration, $plugin_id, $plugin_definition);
-  }
-
+  /**
+   * {@inheritdoc}
+   */
   public static function create(ContainerInterface $container, array $configuration, $plugin_id, $plugin_definition) {
     return new static($configuration, $plugin_id, $plugin_definition);
   }
 
+  /**
+   * {@inheritdoc}
+   */
   public function defaultConfiguration() {
     return [];
   }
 
+  /**
+   * {@inheritdoc}
+   */
   public function calculateDependencies() {
     return [];
   }
 
+  /**
+   * {@inheritdoc}
+   */
   public function getConfiguration() {
     return $this->configuration;
   }
 
+  /**
+   * {@inheritdoc}
+   */
   public function setConfiguration(array $configuration) {
     $this->configuration = $configuration;
   }

src/Plugin/FillPdfActionPluginInterface.php

@@ -5,7 +5,7 @@ namespace Drupal\fillpdf\Plugin;
 use Drupal\Component\Plugin\ConfigurablePluginInterface;
 use Drupal\Component\Plugin\PluginInspectionInterface;
 use Drupal\Core\Plugin\ContainerFactoryPluginInterface;
-use Symfony\Component\HttpFoundation\Response;
+use Drupal\Core\Executable\ExecutableInterface;
 
 /**
  * Defines an interface for FillPDF action plugins.
@@ -17,18 +17,22 @@ use Symfony\Component\HttpFoundation\Response;
  * They may also have side effects, such as saving a file to the file system.
  * They must not, however, end the request.
  */
-interface FillPdfActionPluginInterface extends PluginInspectionInterface, ConfigurablePluginInterface, ContainerFactoryPluginInterface {
+interface FillPdfActionPluginInterface extends PluginInspectionInterface, ConfigurablePluginInterface, ContainerFactoryPluginInterface, ExecutableInterface {
 
   /**
-   * Take action according to the plugin configuration. This will vary for each
-   * action plugin, but it should do something with the PDF (e.g. prepare a
-   * download response, save it to a file, etc.) and return an appropriate
-   * Response (or subclass thereof, such as RedirectResponse) to the caller.
+   * Take action according to the plugin configuration.
+   *
+   * This will vary for each action plugin, but it should do something with the
+   * PDF (e.g. prepare a download response, save it to a file, etc.) and return
+   * an appropriate Response (or subclass thereof, such as RedirectResponse) to
+   * the caller.
    *
    * When you need context info, see if it is passed to you in
    * $this->configuration.
    *
-   * @return Response
+   * @return \Symfony\Component\HttpFoundation\Response
+   *   A response.
+   *
    * @todo Document exceptions thrown if something goes wrong.
    */
   public function execute();