cvs: phd /include PhDHelper.class.php
| From: | Christian Weiske | Date: | Thu, 16 Oct 2008 06:40:43 +0000 |
| Subject: | cvs: phd /include PhDHelper.class.php | ||
| Groups: | php.doc.cvs | ||
| Request: | Send a blank email to doc-cvs+get-2244@lists.php.net to get a copy of this message | ||
cweiske Thu Oct 16 06:40:43 2008 UTC
Modified files:
/phd/include PhDHelper.class.php
Log:
Some docblock enhancements for phdhelper
http://cvs.php.net/viewvc.cgi/phd/include/PhDHelper.class.php?r1=1.9&r2=1.10&diff_format=u
Index: phd/include/PhDHelper.class.php
diff -u phd/include/PhDHelper.class.php:1.9 phd/include/PhDHelper.class.php:1.10
--- phd/include/PhDHelper.class.php:1.9 Sun Jan 27 14:32:33 2008
+++ phd/include/PhDHelper.class.php Thu Oct 16 06:40:42 2008
@@ -1,41 +1,132 @@
<?php
-/* $Id: PhDHelper.class.php,v 1.9 2008/01/27 14:32:33 bjori Exp $ */
+/* $Id: PhDHelper.class.php,v 1.10 2008/10/16 06:40:42 cweiske Exp $ */
+
+/**
+* Base class for PhDTheme
+*/
+class PhDHelper
+{
+ /**
+ * Array of all ids as key and their "attributes" (not xml-atts)
+ * as array.
+ * Created by mktoc.php
+ *
+ * @var array
+ */
+ private $IDs = array();
+
+ /**
+ * Array of <refname> tag contents as key,
+ * and the ID of the section they appear in as value.
+ * Created by mktoc.php
+ *
+ * @var array
+ */
+ private $refs = array();
-class PhDHelper {
- private $IDs = array();
- private $refs = array();
/* abstract */ protected $elementmap = array();
/* abstract */ protected $textmap = array();
private static $autogen = array();
+ /**
+ * Creates the helper object.
+ *
+ * @param array $a Array with ID array as first value, ref array as second.
+ *
+ * @see $IDs
+ * @see $refs
+ */
public function __construct(array $a) {
$this->IDs = $a[0];
$this->refs = $a[1];
}
- final public function getFilename($id) {
+
+ /**
+ * When the tag associated with that $id is to be chunked,
+ * the filename (without extension) is returned.
+ *
+ * @param string $id ID of an element
+ *
+ * @return mixed Filename without extension (string) or false if the element
+ * is not to be chunked
+ *
+ * @see $IDs
+ */
+ final public function getFilename($id)
+ {
return isset($this->IDs[$id]) ? $this->IDs[$id]["filename"] : false;
}
+
final public function getDescription($id, $long = false) {
return $long ?
($this->IDs[$id]["ldesc"] ? $this->IDs[$id]["ldesc"] :
$this->IDs[$id]["sdesc"]) :
($this->IDs[$id]["sdesc"] ? $this->IDs[$id]["sdesc"] :
$this->IDs[$id]["ldesc"]);
}
- final public function getChildren($id) {
+
+ /**
+ * Returns an array of direct children tags with IDs.
+ *
+ * @param string $id ID of an element
+ *
+ * @return array Array of children IDs (empty array when no kids)
+ *
+ * @see $IDs
+ */
+ final public function getChildren($id)
+ {
return $this->IDs[$id]["children"];
}
- final public function getParent($id) {
+
+ /**
+ * Returns ID of the first parental block tag with an ID.
+ *
+ * @param string $id ID of an element
+ *
+ * @return string ID of the parent tag
+ *
+ * @see $IDs
+ */
+ final public function getParent($id)
+ {
return $this->IDs[$id]["parent"];
}
- public function getRefnameLink($ref) {
+
+ /**
+ * Returns the id of the reference page for a given function/method/class.
+ *
+ * @param string $ref Name of referenced object (e.g. "$class",
"$class-$method")
+ *
+ * @return mixed ID (string) of reference page or null if not found.
+ *
+ * @see $refs
+ */
+ public function getRefnameLink($ref)
+ {
return isset($this->refs[$ref]) ? $this->refs[$ref] : null;
}
+
final public function getElementMap() {
return $this->elementmap;
}
final public function getTextMap() {
return $this->textmap;
}
- final public function autogen($text, $lang) {
+
+ /**
+ * Reads $phddir/include/langs/$lang.xml and returns the translation
+ * for the given $text.
+ *
+ * @note
+ * This function is used only internally, it has nothing to do with the
+ * manual content. Used e.g. for autogenerated table of contents titles.
+ *
+ * @param string $text Text to translate ("warning", "toc", "by")
+ * @param string $lang Two-letter ISO code of language (de, en, ..)
+ *
+ * @return string Translated text
+ */
+ final public function autogen($text, $lang)
+ {
if (isset(PhDHelper::$autogen[$lang])) {
return PhDHelper::$autogen[$lang][$text];
}