From: Tim Otten <totten@civicrm.org>
Date: Thu, 13 Apr 2017 16:49:25 +0000 (-0700)
Subject: CRM-20420 - Update sundry comments/docblocks
X-Git-Url: https://vcs.fsf.org/?a=commitdiff_plain;h=3ed92c142653046e234cd0187125f18c008955c6;p=civicrm-core.git

CRM-20420 - Update sundry comments/docblocks
---

diff --git a/CRM/Contact/Form/Task/PDFLetterCommon.php b/CRM/Contact/Form/Task/PDFLetterCommon.php
index ad0dd31f2b..add44a19ef 100644
--- a/CRM/Contact/Form/Task/PDFLetterCommon.php
+++ b/CRM/Contact/Form/Task/PDFLetterCommon.php
@@ -425,6 +425,7 @@ class CRM_Contact_Form_Task_PDFLetterCommon {
 
     $type = $formValues['document_type'];
     $mimeType = self::getMimeType($type);
+    // ^^ Useful side-effect: consistently throws error for unrecognized types.
 
     if ($type == 'pdf') {
       $fileName = "CiviLetter.$type";
diff --git a/CRM/Utils/PDF/Document.php b/CRM/Utils/PDF/Document.php
index 6120321df6..e2dac47b16 100644
--- a/CRM/Utils/PDF/Document.php
+++ b/CRM/Utils/PDF/Document.php
@@ -59,6 +59,8 @@ class CRM_Utils_PDF_Document {
    * @param array $pages
    *   List of HTML snippets.
    * @param string $fileName
+   *   The logical filename to return to client.
+   *   Ex: "HelloWorld.odt".
    * @param array|int $format
    */
   public static function html2doc($pages, $fileName, $format = array()) {
@@ -101,7 +103,13 @@ class CRM_Utils_PDF_Document {
   /**
    * @param object|string $phpWord
    * @param string $ext
+   *   File extension/type.
+   *   Ex: docx, odt, html.
    * @param string $fileName
+   *   The logical filename to return to client.
+   *   Ex: "HelloWorld.odt".
+   *   Alternatively, a full path of a file to display. This seems sketchy.
+   *   Ex: "/var/lib/data/HelloWorld.odt".
    */
   public static function printDoc($phpWord, $ext, $fileName) {
     $formats = array(
@@ -178,7 +186,8 @@ class CRM_Utils_PDF_Document {
    *   Content of formatted/token-replaced document.
    *   List of HTML snippets.
    * @param string $fileName
-   *   Document file name
+   *   The logical filename to return to client.
+   *   Ex: "HelloWorld.odt".
    * @param string $docType
    *   Document type e.g. odt/docx
    * @param clsTbsZip $zip
diff --git a/CRM/Utils/PDF/Utils.php b/CRM/Utils/PDF/Utils.php
index fb3584772e..9b42f7fad8 100644
--- a/CRM/Utils/PDF/Utils.php
+++ b/CRM/Utils/PDF/Utils.php
@@ -39,8 +39,12 @@ class CRM_Utils_PDF_Utils {
    * @param array $text
    *   List of HTML snippets.
    * @param string $fileName
+   *   The logical filename to display.
+   *   Ex: "HelloWorld.pdf".
    * @param bool $output
+   *   FALSE to display PDF. TRUE to return as string.
    * @param null $pdfFormat
+   *   Unclear. Possibly PdfFormat or formValues.
    *
    * @return string|void
    */