Issue #2962458 by Pancho: Document fillpdf_pdf_link()

fillpdf.module

@@ -244,23 +244,33 @@ function fillpdf_file_download_access_alter(&$grants, $file_item, $entity_type,
 }
 
 /**
- * Gets a link to the printable PDF, merged with the passed-in data.
+ * Builds a link generating a printable PDF, merged with the passed-in data.
  *
- * @param $fid
- * @param array|int $nids
- *   If you pass in one value it will merge with that node. If array, it will
- *   merge with multiple nodes, with later nids overriding previous ones.
- * @param array $webform_arr
+ * Note that every time the path is hit, the PDF form will be merged afresh
+ * with the passed-in data, generating a new populated PDF file.
+ *
+ * You may provide multiple IDs of a particular type. In that case, tokens
+ * matching a later node, entity, webform etc. will override previous ones.
+ *
+ * @param int $fid
+ *   FillPDF form ID.
+ * @param int|int[] $nids
+ *   A single node ID or an array thereof.
+ * @param array|array[] $webform_arr
  *   Array of webforms, of this strucure: array('nid'=>1, 'sid'=>1)
  * @param bool $sample
  *   TRUE if you want to populate the form with its own field-names (to get a
  *   gist of PDF)
- * @param $uc_order_ids
- * @param $uc_order_product_ids
- * @param $entity_ids
+ * @param int|int[] $uc_order_ids
+ *   A single Ubercart order ID or an array thereof.
+ * @param int|int[] $uc_order_product_ids
+ *   A single Ubercart order product ID or an array thereof.
+ * @param string|string[] $entity_ids
+ *   A single entity ID given in the form <code>$entity_type:$id</code>, or an
+ *   array thereof.
  *
  * @return string
- *   The file url.
+ *   The file generation URL.
  */
 function fillpdf_pdf_link($fid, $nids = NULL, array $webform_arr = NULL, $sample = FALSE, $uc_order_ids = NULL, $uc_order_product_ids = NULL, $entity_ids = NULL) {
   $query = array('fid' => $fid);