Commit 532ebda4 authored by jcnventura's avatar jcnventura

Improve doxygen comments.

parent a7b19009
body {
direction: rtl;
}
th {
text-align: right;
}
body {direction: rtl;}
th {text-align: right;}
.print-links,
.print-source_url,
.print-taxonomy {
......
body {
margin: 1em;
background-color: #fff;
......@@ -9,21 +8,11 @@ th {
color: #006;
border-bottom: 1px solid #ccc;
}
tr.odd {
background-color: #ddd;
}
tr.even {
background-color: #fff;
}
td {
padding: 5px;
}
#menu {
visibility: hidden;
}
#main {
margin: 1em;
}
tr.odd {background-color: #ddd;}
tr.even {background-color: #fff;}
td {padding: 5px;}
#menu {visibility: hidden;}
#main {margin: 1em;}
a:link {color: #000;}
a:visited {color: #000;}
a:hover {color: #00f;}
......@@ -35,9 +24,7 @@ img.print-logo {border: 0;}
.print-title {}
.print-submitted {font-size: small;}
.print-created {font-size: small;}
.print-taxonomy {
text-align: right;
}
.print-taxonomy {text-align: right;}
.print-taxonomy li {display: inline;}
.print-content {}
.print-hr {
......
......@@ -11,7 +11,7 @@
*/
/**
* Menu callback for the Printer-friendly pages module settings form.
* Form constructor for the Printer-friendly pages module settings form.
*
* @ingroup forms
*/
......@@ -168,7 +168,7 @@ function print_main_settings() {
}
/**
* Validate print_main_settings form.
* Form validation handler for print_main_settings().
*/
function _print_main_settings_validate($form, &$form_state) {
global $base_root;
......@@ -188,7 +188,7 @@ function _print_main_settings_validate($form, &$form_state) {
}
/**
* Menu callback for the Printer-friendly pages HTML settings form.
* Form constructor for the Printer-friendly pages HTML settings form.
*
* @ingroup forms
*/
......
<?php
/**
* @file
* Main API entry point for the Printer, email and PDF versions
*
* @ingroup print
*/
/**
* @defgroup print Printer, email and PDF versions
*
* Welcome to the print module developer's documentation. The interesting
* functions for themers are those that start with 'theme_'.
*
* - Printer-friendly pages
* - @link print.module Module main file @endlink
* - @link print.admin.inc Settings form @endlink
* - @link print.pages.inc HTML generation @endlink
* - @link print.install (Un)Install routines @endlink
* - @link print.tpl.php Page generation template @endlink
* - Send by email
* - @link print_mail.module Module main file @endlink
* - @link print_mail.admin.inc Settings form @endlink
* - @link print_mail.inc Mail form and send mail routine @endlink
* - @link print_mail.install (Un)Install routines @endlink
* - PDF version
* - @link print_pdf.module Module main file @endlink
* - @link print_pdf.admin.inc Settings form @endlink
* - @link print_pdf.pages.inc PDF generation @endlink
* - @link print_pdf.class.inc Auxiliary PHP5 class @endlink
* - @link print_pdf.class_php4.inc Auxiliary PHP4 class @endlink
* - @link print_pdf.install (Un)Install routines @endlink
*/
name = "Printer-friendly pages"
description = "Adds a printer-friendly version link to content and administrative pages."
description = "Generates a printer-friendly version of Drupal pages."
core=7.x
package = "Printer, email and PDF versions"
files[] = print.module
......
<?php
/**
* @defgroup print Printer, email and PDF versions
*
* Welcome to the print module developer's documentation. The interesting
* functions for themers are those that start with 'theme_'.
*
* - Printer-friendly pages
* - @link print.module Module main file @endlink
* - @link print.admin.inc Settings form @endlink
* - @link print.pages.inc HTML generation @endlink
* - @link print.install (Un)Install routines @endlink
* - @link print.tpl.php Page generation template @endlink
* - Send by email
* - @link print_mail.module Module main file @endlink
* - @link print_mail.admin.inc Settings form @endlink
* - @link print_mail.inc Mail form and send mail routine @endlink
* - @link print_mail.install (Un)Install routines @endlink
* - PDF version
* - @link print_pdf.module Module main file @endlink
* - @link print_pdf.admin.inc Settings form @endlink
* - @link print_pdf.pages.inc PDF generation @endlink
* - @link print_pdf.class.inc Auxiliary PHP5 class @endlink
* - @link print_pdf.class_php4.inc Auxiliary PHP4 class @endlink
* - @link print_pdf.install (Un)Install routines @endlink
*/
/**
* @file
* Displays Printer-friendly versions of Drupal pages.
......@@ -77,6 +51,13 @@ function print_print_link() {
);
}
/**
* Implements hook_print_new_window_alter().
*/
function print_print_new_window_alter(&$new_window, $format) {
$new_window = variable_get('print_html_new_window', PRINT_HTML_NEW_WINDOW_DEFAULT);
}
/**
* Implements hook_permission().
*/
......@@ -254,9 +235,10 @@ function print_entity_info_alter(&$info) {
/**
* Auxiliary function to discover a given page's title
*
* @param $path
* @param string $path
* path of the page being identified
* @return
*
* @return string
* string with the page's title
*/
function _print_get_title($path) {
......@@ -279,14 +261,15 @@ function _print_get_title($path) {
* Function made available so that developers may call this function from
* their defined pages/blocks.
*
* @param $path
* @param string $path
* path of the original page (optional). If not specified, the current URL
* is used
* @param $node
* @param object $node
* an optional node object, to be used in defining the path, if used, the
* path argument is irrelevant
* @return
* string with the HTML link to the printer-friendly page
*
* @return string
* HTML link to the printer-friendly page
*/
function print_insert_link($path = NULL, $node = NULL) {
if (function_exists('print_ui_insert_link')) {
......@@ -300,10 +283,11 @@ function print_insert_link($path = NULL, $node = NULL) {
/**
* Check if the link to the PF version is allowed depending on the settings
*
* @param $args
* @param array $args
* array containing the possible parameters:
* teaser, node, type, path
* @return
* view_mode, node, type, path
*
* @return bool
* FALSE if not allowed, TRUE otherwise
*/
function print_link_allowed($args) {
......
......@@ -48,19 +48,22 @@ function print_controller_html() {
* Depending on the type of node, this functions chooses the appropriate
* generator function.
*
* @param $path
* @param string $path
* path of the original page
* @param $format
* @param string $format
* format of the page being generated
* @param $cid
* @param int $cid
* comment ID of the individual comment to be rendered
* @param $teaser
* @param bool $teaser
* if set to TRUE, outputs only the node's teaser
* @return
* array with the fields to be used in the template
*
* @return object
* node-like object to be used in the print template
*
* @see _print_generate_node()
* @see _print_generate_path()
* @see _print_generate_book()
* @see print_preprocess_print()
*/
function print_controller($path, $format, $cid = NULL, $teaser = FALSE) {
if (empty($path)) {
......@@ -180,7 +183,15 @@ function print_preprocess_print(&$variables) {
}
/**
* @todo document this
* Returns HTML for the published line of the print template.
*
* @param array $vars
* An empty associative array
*
* @return string
* HTML text with the published line
*
* @ingroup themeable
*/
function theme_print_published($vars) {
global $base_url;
......@@ -190,7 +201,16 @@ function theme_print_published($vars) {
}
/**
* @todo document this
* Returns HTML for the breadcrumb line of the print template.
*
* @param array $vars
* An associative array containing:
* - $node: the node object
*
* @return string
* HTML text with the breadcrumb
*
* @ingroup themeable
*/
function theme_print_breadcrumb($vars) {
$node = $vars['node'];
......@@ -211,7 +231,15 @@ function theme_print_breadcrumb($vars) {
}
/**
* @todo document this
* Returns HTML for the footer of the print template.
*
* @param array $vars
* An empty associative array
*
* @return string
* HTML text with the footer
*
* @ingroup themeable
*/
function theme_print_footer($vars) {
$footer = '';
......@@ -229,7 +257,18 @@ function theme_print_footer($vars) {
}
/**
* @todo document this
* Returns HTML for the source URL line of the print template.
*
* @param array $vars
* An associative array containing:
* - $url: the URL to the full node view.
* - $node: the node object.
* - $cid; comment ID of the comment to display.
*
* @return string
* HTML text with the footer
*
* @ingroup themeable
*/
function theme_print_sourceurl($vars) {
$sourceurl_date = variable_get('print_sourceurl_date', PRINT_SOURCEURL_DATE_DEFAULT);
......@@ -250,7 +289,15 @@ function theme_print_sourceurl($vars) {
}
/**
* @todo document this
* Returns HTML for the URL list of the print template.
*
* @param array $vars
* An empty associative array
*
* @return string
* HTML text with the URL list
*
* @ingroup themeable
*/
function theme_print_url_list($vars) {
global $_print_urls;
......@@ -276,8 +323,8 @@ function theme_print_url_list($vars) {
/**
* Generates a robots meta tag to tell them what they may index
*
* @return
* string with the meta robots tag
* @return string
* meta robots tag
*/
function _print_robots_meta_generator() {
$robots_meta = array();
......@@ -303,12 +350,12 @@ function _print_robots_meta_generator() {
/**
* Generates the CSS directive to include in the printer-friendly version
*
* @param $expand
* @param bool $expand
* If TRUE, the provided CSS will be expanded, instead of given as a list
* of includes.
*
* @return
* string with applicable CSS
* @return string
* applicable CSS
*/
function _print_css_generator($expand = TRUE) {
$print_css = variable_get('print_css', PRINT_CSS_DEFAULT);
......@@ -348,14 +395,14 @@ function _print_css_generator($expand = TRUE) {
/**
* Callback function for the preg_replace_callback for URL-capable patterns
*
* Manipulate URLs to make them absolute in the URLs list, and to add a
* [n] footnote marker.
* Manipulate URLs to make them absolute in the URLs list, and add a [n]
* footnote marker.
*
* @param $matches
* @param array $matches
* array with the matched tag patterns, usually <a...>+text+</a>
* @return
* tag with re-written URL and when appropriate the [n] index to the
* URL list
*
* @return string
* tag with re-written URL and, if applicable, the [n] index to the URL list
*/
function _print_rewrite_urls($matches) {
global $base_url, $base_root, $_print_urls;
......@@ -429,9 +476,10 @@ function _print_rewrite_urls($matches) {
/**
* Auxiliary function to store the Printer-friendly URLs list as static.
*
* @param $url
* @param string $url
* absolute URL to be inserted in the list
* @return
*
* @return array
* list of URLs previously stored if $url is 0, or the current count
* otherwise.
*/
......@@ -455,11 +503,12 @@ function _print_friendly_urls($url = 0) {
/**
* Check URL list settings for this node
*
* @param node
* @param object $node
* node object
* @param $format
* @param string $format
* format of the page being generated
* @return
*
* @return bool
* TRUE if URL list should be displayed, FALSE otherwise
*/
function _print_url_list_enabled($node, $format) {
......@@ -477,16 +526,17 @@ function _print_url_list_enabled($node, $format) {
/**
* Prepare a Printer-friendly-ready node body for content nodes
*
* @param $nid
* @param int $nid
* node ID of the node to be rendered into a printer-friendly page
* @param $format
* @param string $format
* format of the page being generated
* @param $cid
* @param int $cid
* comment ID of the individual comment to be rendered
* @param $teaser
* @param bool $teaser
* if set to TRUE, outputs only the node's teaser
* @return
* filled array ready to be used in the template
*
* @return object
* filled node-like object to be used in the print template
*/
function _print_generate_node($nid, $format, $cid = NULL, $teaser = FALSE) {
global $_print_urls;
......@@ -518,10 +568,6 @@ function _print_generate_node($nid, $format, $cid = NULL, $teaser = FALSE) {
// Disable the links area
unset($node->content['links']);
// Disable fivestar widget output @todo check this
unset($node->content['fivestar_widget']);
// Disable service links module output @todo check this
unset($node->content['service_links']);
$build = $node->content;
unset($node->content);
......@@ -585,12 +631,13 @@ function _print_generate_node($nid, $format, $cid = NULL, $teaser = FALSE) {
/**
* Prepare a Printer-friendly-ready node body for non-content pages
*
* @param $path
* @param string $path
* path of the node to be rendered into a printer-friendly page
* @param $format
* @param string $format
* format of the page being generated
* @return
* filled array ready to be used in the template
*
* @return object
* filled node-like object to be used in the print template
*/
function _print_generate_path($path, $format) {
global $_print_urls;
......@@ -645,12 +692,13 @@ function _print_generate_path($path, $format) {
/**
* Prepare a Printer-friendly-ready node body for book pages
*
* @param $nid
* @param int $nid
* node ID of the node to be rendered into a printer-friendly page
* @param $format
* @param string $format
* format of the page being generated
* @return
* filled array ready to be used in the template
*
* @return object
* filled node-like object to be used in the print template
*/
function _print_generate_book($nid, $format) {
global $_print_urls;
......@@ -677,9 +725,5 @@ function _print_generate_book($nid, $format) {
$pattern = '!<(a\s[^>]*?)>(.*?)(</a>)!is';
$node->content = preg_replace_callback($pattern, '_print_rewrite_urls', $node->content);
// The title is already displayed by the book_recurse, so avoid duplication
// @todo check this
$node->title = '';
return $node;
}
......@@ -14,7 +14,7 @@
@include_once('Mail/mime.php');
/**
* Menu callback for the send by email module settings form.
* Form constructor for the send by email module settings form.
*
* @ingroup forms
*/
......
......@@ -16,7 +16,7 @@ require_once(DRUPAL_ROOT . '/' . drupal_get_path('module', 'print') . '/print.pa
@include_once('Mail/mime.php');
/**
* Menu callback for the send by email form.
* Form constructor for the send by email form.
*
* @ingroup forms
*/
......@@ -173,12 +173,17 @@ function print_mail_form($form, &$form_state) {
}
/**
* Theme function for the send by-email form submission.
* Returns HTML for the send by-email form.
*
* Adds a class to the form labels. This class is used to place the label on
* the left of the input fields.
*
* @param array $form
* Form array
*
* @see print_mail_form()
* @ingroup forms
* @ingroup themeable
*/
function theme_print_mail_form($form) {
drupal_add_css(drupal_get_path('module', 'print_mail') . '/css/print_mail.theme.css');
......@@ -200,8 +205,9 @@ function theme_print_mail_form($form) {
}
/**
* Validate the send by-email form submission.
* Form validation handler for print_mail_form().
*
* @see print_mail_form()
* @ingroup forms
*/
function print_mail_form_validate($form, &$form_state) {
......@@ -259,8 +265,9 @@ function print_mail_form_validate($form, &$form_state) {
}
/**
* Process the send by-email form submission.
* Form submission handler for print_mail_form().
*
* @see print_mail_form()
* @see print_controller()
* @ingroup forms
*/
......@@ -342,9 +349,10 @@ function print_mail_form_submit($form, &$form_state) {
*
* Replace spaces in URLs with %20
*
* @param $matches
* @param array $matches
* array with the matched tag patterns, usually <a...>+text+</a>
* @return
*
* @return string
* tag with re-written URL
*/
function _print_mail_encode_urls($matches) {
......
......@@ -49,9 +49,6 @@ function print_mail_permission() {
*/
function print_mail_theme() {
return array(
'print_mail_format_link' => array(
'variables' => array(),
),
'print_mail_form' => array(
'variables' => array('form' => NULL),
'file' => 'print_mail.inc',
......@@ -167,6 +164,19 @@ function print_mail_cron_queue_info() {
return $queues;
}
/**
* Worker callback for print_mail_cron_queue_info()
*
* @param array $data
* An associative array containing:
* - module: A module name to invoke hook_mail() on.
* - key: A key to identify the e-mail sent.
* - to: The e-mail address or addresses where the message will be sent to.
* - language: Language object to use to compose the e-mail.
* - params: Optional parameters to build the e-mail.
* - from: Sets From to this value, if given.
* These are the input arguments of the drupal_mail() function.
*/
function print_mail_send($data) {
drupal_mail($data['module'], $data['key'], $data['to'], $data['language'], $data['params'], $data['from']);
}
......@@ -229,9 +239,10 @@ function print_mail_mail($key, &$message, $params) {
/**
* Access callback to check a combination of user_acess() and page access
*
* @param $permission
* @param string $permission
* permission required to view the page
* @return
*
* @return bool
* TRUE if the user has permission to view the page, FALSE otherwise
*/
function _print_mail_access($permission) {
......@@ -271,13 +282,14 @@ function _print_mail_access($permission) {
* Function made available so that developers may call this function from
* their defined pages/blocks.
*
* @param $path
* @param string $path
* path of the original page (optional). If not specified, the current URL
* is used
* @param $node
* @param object $node
* an optional node object, to be used in defining the path, if used, the
* path argument is irrelevant
* @return
*
* @return string
* string with the HTML link to the printer-friendly page
*/
function print_mail_insert_link($path = NULL, $node = NULL) {
......@@ -292,10 +304,11 @@ function print_mail_insert_link($path = NULL, $node = NULL) {
/**
* Check if the link to send by email is allowed depending on the settings
*
* @param $args
* @param array $args
* array containing the possible parameters:
* teaser, node, type, path
* @return
* view_mode, node, type, path
*
* @return bool
* FALSE if not allowed, TRUE otherwise
*/
function print_mail_link_allowed($args) {
......
......@@ -11,10 +11,10 @@
*/
/**
* Menu callback for the PDF version module settings form.
* Form constructor for the PDF version module settings form.
*
* @ingroup forms
* @see _print_pdf_tools()
* @ingroup forms
*/
function print_pdf_settings() {
$pdf_tools = _print_pdf_tools();
......@@ -145,7 +145,10 @@ function print_pdf_settings() {
}
/**
* Validate print_pdf_settings form.
* Form validation handler for print_pdf_settings().
*
* @see print_pdf_settings()
* @ingroup forms
*/
function _print_pdf_settings_validate($form, &$form_state) {
if (empty($form_state['values']['print_pdf_pdf_tool'])) {
......@@ -154,10 +157,9 @@ function _print_pdf_settings_validate($form, &$form_state) {
}
/**
* Menu callback for the TCPDF options settings form.
* Form constructor for the TCPDF options settings form.
*
* @ingroup forms
* @see _print_pdf_tools()
*/
function print_pdf_tcpdf_settings() {
$form['settings'] = array(
......@@ -195,7 +197,10 @@ function print_pdf_tcpdf_settings() {
}
/**
* Validate print_pdf_tcpdf_settings form.
* Form validation handler for print_pdf_tcpdf_settings().
*
* @see print_pdf_tcpdf_settings()
* @ingroup forms
*/
function _print_pdf_tcpdf_settings_validate($form, &$form_state) {
if ($form_state['values']['print_pdf_font_size'] < 1) {
......@@ -204,10 +209,9 @@ function _print_pdf_tcpdf_settings_validate($form, &$form_state) {
}
/**
* Menu callback for the dompdf options settings form.
* Form constructor for the dompdf options settings form.
*
* @ingroup forms
* @see _print_pdf_tools()
*/
function print_pdf_dompdf_settings() {
$form['settings'] = array(
......@@ -226,10 +230,9 @@ function print_pdf_dompdf_settings() {
}
/**
* Menu callback for the wkhtmltopdf options settings form.
* Form constructor for the wkhtmltopdf options settings form.
*
* @ingroup forms
* @see _print_pdf_tools()
*/
function print_pdf_wkhtmltopdf_settings() {
$form['settings'] = array(
......@@ -252,7 +255,7 @@ function print_pdf_wkhtmltopdf_settings() {
/**
* Auxiliary function to locate suitable PDF generation tools
*
* @return
* @return array
* array of filenames with the include-able PHP file of the located tools
*/
function _print_pdf_tools() {
......
......@@ -28,7 +28,7 @@ function print_pdf_drush_command() {
$items = array();
$items['print-pdf-download'] = array(
'description' => 'Download a PDF library.',
'description' => 'Download and extract a PDF library.',
'arguments' => array(
'library' => dt('The PDF library to download. Either tcpdf, dompdf or wkhtmltopdf.'),
),
......@@ -44,6 +44,9 @@ function print_pdf_drush_command() {
/**
* Download and extract PDF archive.
*
* @param string $library
* library to download
*/
function drush_print_pdf_download($library) {
if (isset($library)) {
......@@ -98,7 +101,13 @@ function drush_print_pdf_download($library) {
}
/**
* Discover the correct URL of the package to download
* Discover the correct URL of the package to download.
*
* @param string $library
* library to download
*
* @return string
* URL of the file to download, FALSE if not known
*/
function _drush_print_pdf_download_url($library) {
$ret = FALSE;
......@@ -135,7 +144,13 @@ function _drush_print_pdf_download_url($library) {
}
/**
* Helper to download and extract the zip/tar archive.
* Helper to extract the downloaded zip/tar archive.
*
* @param string $filename
* filename of the file to extract
*
* @return bool
* TRUE on success, FALSE on failure
*/
function _drush_print_pdf_download_extract($filename) {
$arch_ret = FALSE;
......
......@@ -37,6 +37,13 @@ function print_pdf_print_link() {
);
}
/**
* Implements hook_print_new_window_alter().
*/
function print_pdf_print_new_window_alter(&$new_window, $format) {
$new_window = (variable_get('print_pdf_content_disposition', PRINT_PDF_CONTENT_DISPOSITION_DEFAULT) == 1);
}
/**
* Implements hook_permission().
*/
......@@ -54,9 +61,6 @@ function print_pdf_permission() {
*/
function print_pdf_theme() {
return array(
'print_pdf_format_link' => array(
'variables' => array(),
),
'print_pdf_dompdf_footer' => array(
'variables' => array('html' => ''),
'file' => 'print_pdf.pages.inc',
...