Removed: Unused file

Added: Comments on dockblock
Updated: Readme file

Author: rosario-fiorella

comblock-html.php

@@ -1,6 +1,8 @@
 <?php
 
 /**
+ * Plugin bootstrap file for Comblock HTML UI.
+ *
  * @link              https://github.com/rosario-fiorella/wordpress-comblock-html/
  * @since             1.0.0
  * @package           wordpress-comblock-html
@@ -9,10 +11,10 @@
  * @wordpress-plugin
  * Plugin Name:       Comblock HTML UI
  * Plugin URI:        https://github.com/rosario-fiorella/wordpress-comblock-html/
- * Description:       WordPress plugin that provides a service class to generate html 
+ * Description:       WordPress plugin that provides a service class to generate HTML.
  * Version:           1.0.0
- * Requires at least: 6.0
- * Requires PHP:      7.4
+ * Requires at least: 6.8
+ * Requires PHP:      8.1
  * Author:            Rosario Fiorella
  * Author URI:        https://github.com/rosario-fiorella/
  * Text Domain:       comblock-html
@@ -26,18 +28,14 @@
     die;
 }
 
-if (defined('WP_CLI') && WP_CLI) {
-    return;
-}
+try {
+    require_once plugin_dir_path(__FILE__) . 'includes/class-comblock-html.php';
 
-/**
- * @see https://semver.org
- */
-define('COMBLOCK_HTML_VERSION', '1.0.0');
-define('COMBLOCK_HTML_DOMAIN', 'comblock-html');
-define('COMBLOCK_HTML_PLUGIN_FILE', __FILE__);
-
-require_once plugin_dir_path(__FILE__) . 'includes/class-comblock-html.php';
-
-$comblock_html = new Comblock_Html();
-$comblock_html->run();
+    $comblock_html = new Comblock_Html();
+    $comblock_html->run();
+} catch (Throwable $e) {
+    add_action('admin_notices', function () use ($e) {
+        $html = sprintf('<div class="notice notice-error is-dismissible"><p>%s</p></div>',  esc_html($e->getMessage()));
+        echo wp_kses_post($html);
+    });
+}

includes/class-comblock-html-activator.php

@@ -1,87 +1,90 @@
 <?php
 
 /**
+ * Manages the construction of the HTML document using Comblock_Html_Dom objects.
+ *
  * @package comblock-html
  * @subpackage comblock-html/includes
  */
 class Comblock_Html_Document
 {
     /**
+     * The DOMDocument representing the entire HTML document.
+     *
      * @since 1.0.0
      * @var DOMDocument $dom
      */
     public DOMDocument $dom;
 
     /**
+     * Collection of Comblock_Html_Dom nodes to be inserted into the document.
+     *
      * @since 1.0.0
      * @access protected
-     * @var ArrayObject $schema
+     * @var ArrayObject<int, Comblock_Html_Dom> $schema
      */
     protected ArrayObject $schema;
 
     /**
+     * Initializes the instance with a new DOMDocument and an empty schema.
+     *
      * @since 1.0.0
      */
     public function __construct()
     {
         $this->dom = new DOMDocument();
-
         $this->schema = new ArrayObject();
     }
 
     /**
+     * Adds a Comblock_Html_Dom node to the collection.
+     *
      * @since 1.0.0
-     * @param Comblock_Html_Dom $node
-     * @return void
+     * @param Comblock_Html_Dom $node The node to add to the schema.
      */
     public function add(Comblock_Html_Dom $node): void
     {
         $this->schema->append($node);
     }
 
     /**
+     * Generates the HTML output by processing the node structure and returning the markup.
+     *
      * @since 1.0.0
-     * @return string
+     * @return string The generated HTML markup.
      */
     public function view(): string
     {
         $this->process($this->schema->getArrayCopy());
 
-        return $this->dom->saveHTML();
+        return $this->dom->saveHTML() ?: '';
     }
 
     /**
+     * Recursive process that builds DOM nodes from the Comblock_Html_Dom node structure.
+     *
      * @since 1.0.0
      * @access protected
-     * @param Comblock_Html_Node[] $scheme
-     * @param null|DOMElement $parent
-     * @return void
+     * @param Comblock_Html_Dom[] $scheme Array of nodes to process.
+     * @param DOMElement|null $parent The parent DOM node where children will be appended. If null, appends to the root.
      */
     protected function process(array $scheme = [], ?DOMElement $parent = null): void
     {
         foreach ($scheme as $node) {
-            /**
-             * @var Comblock_Html_Dom $node
-             */
-            $node;
+            /** @var Comblock_Html_Dom $node */
 
-            /**
-             * @var DOMElement $element
-             */
+            /** @var DOMElement $element Newly created DOM node */
             $element = $this->dom->createElement($node->get_tag(), $node->get_value());
+
             foreach ($node->get_attributes() as $name => $value) {
                 $element->setAttribute($name, $value);
             }
 
             if ($parent) {
-                /**
-                 * @var null|DOMElement $child
-                 */
+                /** @var DOMElement $child Newly appended child node */
                 $child = $parent->appendChild($element);
             } else {
-                /**
-                 * @var null|DOMElement $child
-                 */
+                /** @var DOMElement $child Newly appended child node */
                 $child = $this->dom->appendChild($element);
             }
 

includes/class-comblock-html-deactivator.php

@@ -1,49 +1,47 @@
 <?php
 
 /**
+ * Represents a DOM element within the comblock-html system.
+ *
  * @since 1.0.0
  * @package comblock-html
  * @subpackage comblock-html/includes
+ * @author Rosario Fiorella
  */
 class Comblock_Html_Dom
 {
-	/**
-	 * @since 1.0.0
-	 */
-	use Comblock_Html_Attribute;
+    use Comblock_Html_Attribute;
+    use Comblock_Html_Content;
+    use Comblock_Html_Children;
 
-	/**
-	 * @since 1.0.0
-	 */
-	use Comblock_Html_Content;
+    /**
+     * The HTML tag name for this DOM element.
+     *
+     * @since 1.0.0
+     * @access protected
+     * @var string
+     */
+    protected string $tag = '';
 
-	/**
-	 * @since 1.0.0
-	 */
-	use Comblock_Html_Children;
+    /**
+     * Initializes the DOM element with a sanitized tag name.
+     *
+     * @since 1.0.0
+     * @param string $tag The name of the HTML tag.
+     */
+    public function __construct(string $tag)
+    {
+        $this->tag = sanitize_key($tag);
+    }
 
-	/**
-	 * @since 1.0.0
-	 * @access protected
-	 * @var string $tag
-	 */
-	protected string $tag;
-
-	/**
-	 * @since 1.0.0
-	 * @param string $tag
-	 */
-	public function __construct(string $tag)
-	{
-		$this->tag = esc_html($tag);
-	}
-
-	/**
-	 * @since 1.0.0
-	 * @return string
-	 */
-	public function get_tag(): string
-	{
-		return $this->tag;
-	}
+    /**
+     * Retrieves the tag name of this DOM element.
+     *
+     * @since 1.0.0
+     * @return string The HTML tag name.
+     */
+    public function get_tag(): string
+    {
+        return $this->tag;
+    }
 }