From 2ee2dacaf6f40f6feb1201720927b6b7e7b873f1 Mon Sep 17 00:00:00 2001 From: Michael Wallner Date: Tue, 17 Dec 2013 10:25:33 +0100 Subject: [PATCH] docs & typos --- mdref/Action.php | 7 ++++++ mdref/ExceptionHandler.php | 11 +++++++++ mdref/Finder.php | 3 +++ mdref/RefEntry.php | 46 +++++++++++++++++++++++++++++++++++++- mdref/RefListing.php | 35 ++++++++++++++++++++++++++++- public/index.js | 4 ++-- 6 files changed, 102 insertions(+), 4 deletions(-) diff --git a/mdref/Action.php b/mdref/Action.php index 511e3a6..462e35b 100644 --- a/mdref/Action.php +++ b/mdref/Action.php @@ -4,6 +4,9 @@ namespace mdref; use http\Controller\Observer; +/** + * The sole action controller of mdref + */ class Action extends Observer { private function serveReference(\http\Controller $ctl) { @@ -34,6 +37,10 @@ class Action extends Observer } } + /** + * Implements \SplObserver + * @param \SplSubject $ctl + */ function update(\SplSubject $ctl) { /* @var \http\Controller $ctl */ try { diff --git a/mdref/ExceptionHandler.php b/mdref/ExceptionHandler.php index d184ea0..0edf728 100644 --- a/mdref/ExceptionHandler.php +++ b/mdref/ExceptionHandler.php @@ -4,6 +4,9 @@ namespace mdref; use http\Env as HTTP; +/** + * mdref exception handler + */ class ExceptionHandler { function __construct() { @@ -24,6 +27,14 @@ class ExceptionHandler return true; } + /** + * Format an exception as HTML and send appropriate exception info as HTTP headers + * @param \Exception $e + * @param array $title_tag + * @param array $message_tag + * @param array $trace_tag + * @return string + */ static function html(\Exception $e, array $title_tag = ["h1"], array $message_tag = ["p"], array $trace_tag = ["pre", "style='font-size:smaller'"]) { if ($e instanceof \http\Controller\Exception) { $code = $e->getCode() ?: 500; diff --git a/mdref/Finder.php b/mdref/Finder.php index 8f0f231..e5cb7fb 100644 --- a/mdref/Finder.php +++ b/mdref/Finder.php @@ -36,6 +36,9 @@ class Finder $this->baseUrl = $baseUrl; } + /** + * @return \http\Controller\Url + */ function getBaseUrl() { return $this->baseUrl; } diff --git a/mdref/RefEntry.php b/mdref/RefEntry.php index 0becc69..9db99f7 100644 --- a/mdref/RefEntry.php +++ b/mdref/RefEntry.php @@ -2,6 +2,9 @@ namespace mdref; +/** + * The RefEntry class represents a reference entry, i.e. a .md file + */ class RefEntry { /** @@ -19,17 +22,28 @@ class RefEntry */ protected $file; + /** + * @param \mdref\Path $path + * @param type $entry + */ function __construct(Path $path, $entry = null) { $this->path = $path; $this->entry = trim($entry ?: $path->getPathName(), DIRECTORY_SEPARATOR); } + /** + * Clean up the file handle + */ function __destruct() { if (is_resource($this->file)) { fclose($this->file); } } + /** + * Format as URL + * @return string + */ function formatUrl() { return htmlspecialchars($this->entry); } @@ -54,6 +68,11 @@ class RefEntry return $link; } + /** + * Format as link text + * @param bool $basename whether to use the basename only + * @return string + */ function formatLink($basename = false) { $link = ""; if (strlen($this->entry)) { @@ -63,6 +82,10 @@ class RefEntry return htmlspecialchars($link); } + /** + * Create a consolidated Path of this entry + * @return \mdref\Path + */ function getPath() { $path = $this->path; $file = $path($this->entry); @@ -82,12 +105,20 @@ class RefEntry } } + /** + * Read the title of the refentry + * @return string + */ function readTitle() { $this->openFile(); fseek($this->file, 1, SEEK_SET); return htmlspecialchars(fgets($this->file)); } + /** + * Read the description of the refentry + * @return string + */ function readDescription() { $this->openFile(); fseek($this->file, 0, SEEK_SET); @@ -96,6 +127,13 @@ class RefEntry return htmlspecialchars(fgets($this->file)); } + /** + * Format a "Edit me" URL. The project reference top directory needs a + * »name«.mdref file besides its »name«.md entry point with the edit URL + * printf template as content. The sole printf argument is the relative + * path of the entry. + * @return string + */ function formatEditUrl() { $path = $this->path; $base = current(explode(DIRECTORY_SEPARATOR, $path->getPathName())); @@ -106,6 +144,12 @@ class RefEntry } } + /** + * Recurse into the reference tree + * @param \mdref\Finder $refs + * @param string $pattern + * @param callable $cb + */ function recurse(Finder $refs, $pattern, callable $cb) { $path = $refs->find($refs->getBaseUrl()->mod($this->entry)); foreach (new RefListing($path, $refs->glob($path, $pattern)) as $entry) { @@ -115,4 +159,4 @@ class RefEntry }); } } -} \ No newline at end of file +} diff --git a/mdref/RefListing.php b/mdref/RefListing.php index fd86b94..3816be2 100644 --- a/mdref/RefListing.php +++ b/mdref/RefListing.php @@ -2,6 +2,9 @@ namespace mdref; +/** + * A list of markdown reference files + */ class RefListing implements \Countable, \Iterator { /** @@ -25,30 +28,56 @@ class RefListing implements \Countable, \Iterator }, $files); } + /** + * Implements \Countable + * @return int + */ function count() { return count($this->entries); } + /** + * Implements \Iterator + */ function rewind() { reset($this->entries); } + /** + * Implements \Iterator + * @return bool + */ function valid() { return null !== key($this->entries); } + /** + * Implements \Iterator + * @return string + */ function key() { return $this->path->getSubPath(current($this->entries)); } + /** + * Implements \Iterator + */ function next() { next($this->entries); } - + + /** + * Implements \Iterator + * @return \mdref\RefEntry + */ function current() { return new RefEntry($this->path, $this->key());//$this->format($this->key()); } + /** + * Get the parent reference entry + * @return null|\mdref\RefEntry + */ function getParent() { switch ($parent = dirname($this->path->getPathName())) { case ".": @@ -59,6 +88,10 @@ class RefListing implements \Countable, \Iterator } } + /** + * Get the reference entry this reflist is based of + * @return \mdref\RefEntry + */ function getSelf() { return new RefEntry($this->path); } diff --git a/public/index.js b/public/index.js index 35587b7..62ccba6 100644 --- a/public/index.js +++ b/public/index.js @@ -175,12 +175,12 @@ $(function() { $(window).scrollTop($(c).offset().top - 100); scrolled = true; } - blink(c); + mdref.blink(c); } } : function(i, c) { if (c.textContent === hash) { $(window).scrollTop($(c).offset().top - 100); - blink(c); + mdref.blink(c); return false; } }); -- 2.30.2