docs & typos

diff --git a/mdref/Action.php b/mdref/Action.php
index 511e3a6c8f412d21210f780b2e9b4ab68f494939..462e35b56e0e4810cbee75aa1e6ddeb382abe990 100644 (file)
--- 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 d184ea08650ad423d0edd7021ce22caa3a03a5a2..0edf7289ad9e33111e18b04651a6481e8fed0d33 100644 (file)
--- 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 8f0f2315e41a56c8ede79481f00dcc7db8ceba7a..e5cb7fb68c16816a618ddcb285ffddd8e8ea5f82 100644 (file)
--- 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 0becc69988b52ae844c52b108959b5194fd1b5f2..9db99f7aa529a16a98e9574b9e8883087bacb743 100644 (file)
--- 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 fd86b945131c4a6b2a9f4005f87c89601aa639fe..3816be23d60beb0b8a8c6ab33993e7efc39d7831 100644 (file)
--- 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 35587b7a2b459c848d84fa063a8e93d29dcfd44f..62ccba63c8ffd9eac673bc40e8dbdd69a2c49079 100644 (file)
--- 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;
                                        }
                                });