Code Block Documentation.

francis94c · Jul 1, 2019 · f415bb0 · f415bb0
1 parent 6b6b8c9
commit f415bb0
Show file tree

Hide file tree

Showing 2 changed files with 86 additions and 34 deletions.
diff --git a/libraries/Blogger.php b/libraries/Blogger.php
@@ -1,32 +1,74 @@
 <?php
+declare(strict_types=1);
 defined('BASEPATH') OR exit('No direct script access allowed');
 
 class Blogger {
 
+  /**
+   * Code Igniter Instance
+   * @var [type]
+   */
   private $ci;
-
+  /**
+   * Code Igniter DB Forge instance reference for simplicity.
+   * @var [type]
+   */
   private $dbforge;
-
+  /**
+   * Current Blog Table Name.
+   * @var [type]
+   */
   private $table_name;
-
+  /**
+   * String prefixed with ever blog name.
+   * @var string
+   */
   const TABLE_PREFIX = "blogger_posts";
-
+  /**
+   * Name of this package for simplicity.
+   * @var string
+   */
   const PACKAGE = "francis94c/blog";
-
+  /**
+   * Name of the dependent package for markdown.
+   * @var string
+   */
   const MARKDOWN_PACKAGE = "francis94c/ci-parsedown";
-
+  /**
+   * Blog post create action.
+   * @var string
+   */
   const CREATE = "create";
-
+  /**
+   * Blog post create and publish action.
+   * @var string
+   */
   const CREATE_AND_PUBLISH = "createAndPublish";
-
+  /**
+   * Blog post edit action.
+   * @var string
+   */
   const EDIT = "edit";
-
+  /**
+   * Blog post publish action.
+   * @var string
+   */
   const PUBLISH = "publish";
-
+  /**
+   * Blog post delete action.
+   * @var string
+   */
   const DELETE = "delete";
-
+  /**
+   * Blog post abort acction. This is an action taken internally when other
+   * actions fail.
+   * @var string
+   */
   const ABORT = "abortAction";
-
+  /**
+   * Constructor
+   * @param mixed $params associative array of parameters. See README.md
+   */
   function __construct($params=null) {
     $this->ci =& get_instance();
     $this->ci->load->database();
@@ -39,13 +81,19 @@ function __construct($params=null) {
   }
   /**
    * [install description]
-   * @param  [type] $adminTableName          [description]
-   * @param  [type] $adminTableName          [description]
-   * @param  [type] $adminIdColumnName       [description]
-   * @param  [type] $adminIdColumnConstraint [description]
-   * @return [type]                          [description]
+   * @param  string $blogName                Name of blog tabke to install.
+   *
+   * @param  string $adminTableName          Name of admi table to restrict post to.
+   *
+   * @param  string $adminIdColumnName       Name of the column to add a foreign
+   *                                         key constarint to the blog table with.
+   *
+   * @param  int    $adminIdColumnConstraint The column constarint or limit of
+   *                                         $adminIdColumnName.
+   *
+   * @return bool                            True on Success, False if Not.
    */
-  public function install($blogName=null, $adminTableName = null, $adminIdColumnName = null, $adminIdColumnConstraint = null) {
+  public function install(string $blogName=null, string $adminTableName=null, string $adminIdColumnName=null, int $adminIdColumnConstraint=null): bool {
     $blogName = $blogName == null ? $this->table_name : self::TABLE_PREFIX . "_" . $blogName;
     $this->ci->load->dbforge();
     $this->ci->dbforge->add_field("id");
@@ -93,11 +141,11 @@ public function install($blogName=null, $adminTableName = null, $adminIdColumnNa
     return true;
   }
   /**
-   * [setBlog description]
-   * @param [type] $name [description]
+   * Sets the name of the current blog table.
+   * @param string $name name of a blog table.
    * @deprecated
    */
-  public function setName($name) {
+  public function setName(string $name): void {
     $this->table_name = self::TABLE_PREFIX . "_" . $name;
     $this->ci->bmanager->setBlogName($name != "" ? $name : null);
   }

diff --git a/unit_tests/BlogTest.php b/unit_tests/BlogTest.php
@@ -1,16 +1,17 @@
 <?php
+declare(strict_types=1);
 use PHPUnit\Framework\TestCase;
 
 final class BlogTest extends TestCase {
 
   /**
-   * [private description]
+   * Code Igniter Instance.
    * @var [type]
    */
   private static $ci;
 
   /**
-   * [setUp description]
+   * Prerquisites for the Unit Tests.
    */
   public static function setUpBeforeClass(): void {
     self::$ci =& get_instance();
@@ -25,10 +26,10 @@ public static function setUpBeforeClass(): void {
     self::$ci->load->splint("francis94c/blog", "+Blogger", null, "blogger");
   }
   /**
-   * [testInstallBlog description]
-   * @return [type] [description]
+   * Test all functions relating to the installation of a blog. this is just the
+   * creation of tables under the hood.
    */
-  public function testInstallBlog() {
+  public function testInstallBlog(): void {
     $this->assertTrue(self::$ci->blogger->install("test_blog"), "Blog Installed Successfuly without admin ID constraint.");
     $this->assertTrue(self::$ci->db->table_exists(Blogger::TABLE_PREFIX . "_test_blog"));
     $fields = self::$ci->db->list_fields(Blogger::TABLE_PREFIX . "_test_blog");
@@ -49,21 +50,23 @@ public function testInstallBlog() {
     $this->assertContains("date_published", $fields);
   }
   /**
-   * [testUI description]
-   * @return [type] [description]
+   * Test UI functions. This just out pust  HTML for manual inspection. The optimal
+   * inspection for this part is to use the Code Igniter Unit Testing system that
+   * outputs to a browser. See https://splint.cynobit/wiki
+   *
    * @depends testInstallBlog
    */
-  public function testUI() {
+  public function testUI(): void {
     $this->assertTrue(self::$ci->blogger->loadEditor("callback"), "Load Editor");
     self::$ci->blogger->setBlog("test_blog");
     $this->assertTrue(self::$ci->blogger->renderPostItems(null, null, null, 1, 0), "Test load empty posts set");
   }
   /**
-   * [testBlogSave description]
-   * @return [type] [description]
+   * Test the blog post saving functionality of the library.
+   * Create, Save, Publish, Create and Publish
    * @depends testInstallBlog
    */
-  public function testBlogSave() {
+  public function testBlogSave(): void {
     // No Admin.
     self::$ci->blogger->setBlog("test_blog");
     $_POST["action"] = "save";
@@ -114,16 +117,17 @@ public function testBlogSave() {
     $this->assertEquals(1, $post["published"]);
     $this->assertNotEquals(null, $post["date_published"]);
     $this->assertEquals(Blogger::ABORT, self::$ci->blogger->savePost(), "No 2 blog posts can have the same title.");
+    // TODO: With Admin.
   }
   /**
-   * [testDynamicFunctions description]
+   * Test Setters and Getters.
    */
   public function testDynamicFunctions(): void {
     self::$ci->blogger->setBlog("rocket_blog");
     $this->assertEquals(Blogger::TABLE_PREFIX . "_rocket_blog", self::$ci->blogger->getName(), "Blogger setBlog works.");
   }
   /**
-   * [tearDownAfterClass description]
+   * Clear and Free up persistent used resources for this test class.
    */
   public static function tearDownAfterClass(): void {
     self::$ci->db->empty_table("admins");