@qubit-ltd/jsdoc-theme 1.4.0 → 1.5.0

package/README.md

@@ -1,6 +1,6 @@
 # qubit-jsdoc-theme
 
-[![Stars](https://img.shields.io/github/stars/Haixing-Hu/qubit-jsdoc-theme)](https://github.com/Haixing-Hu/qubit-jsdoc-theme) [![Fork](https://img.shields.io/github/forks/Haixing-Hu/qubit-jsdoc-theme)](https://github.com/Haixing-Hu/qubit-jsdoc-theme/fork) ![Version](https://img.shields.io/badge/version-1.4.0-005bff) [![Issues Open](https://img.shields.io/github/issues/Haixing-Hu/qubit-jsdoc-theme)](https://github.com/Haixing-Hu/qubit-jsdoc-theme/issues) [![Contributors](https://img.shields.io/github/contributors/Haixing-Hu/qubit-jsdoc-theme)](https://github.com/Haixing-Hu/qubit-jsdoc-theme/graphs/contributors) [![license](https://img.shields.io/github/license/Haixing-Hu/qubit-jsdoc-theme)](https://github.com/Haixing-Hu/qubit-jsdoc-theme/blob/master/LICENSE)
+[![Stars](https://img.shields.io/github/stars/Haixing-Hu/qubit-jsdoc-theme)](https://github.com/Haixing-Hu/qubit-jsdoc-theme) [![Fork](https://img.shields.io/github/forks/Haixing-Hu/qubit-jsdoc-theme)](https://github.com/Haixing-Hu/qubit-jsdoc-theme/fork) ![Version](https://img.shields.io/badge/version-1.5.0-005bff) [![Issues Open](https://img.shields.io/github/issues/Haixing-Hu/qubit-jsdoc-theme)](https://github.com/Haixing-Hu/qubit-jsdoc-theme/issues) [![Contributors](https://img.shields.io/github/contributors/Haixing-Hu/qubit-jsdoc-theme)](https://github.com/Haixing-Hu/qubit-jsdoc-theme/graphs/contributors) [![license](https://img.shields.io/github/license/Haixing-Hu/qubit-jsdoc-theme)](https://github.com/Haixing-Hu/qubit-jsdoc-theme/blob/master/LICENSE)
 <br>
 
 **Based on [clean-jsdoc-theme](https://github.com/ankitskvmdam/clean-jsdoc-theme) v4.3.0**
@@ -10,6 +10,8 @@
 ## Enhanced Features (New in qubit-jsdoc-theme)
 
 - **🆕 Smart Properties Table:** Automatically generates a dedicated "Properties" section for classes, displaying all class properties in a clean table format with type information and descriptions derived from individual field JSDoc comments.
+- **🆕 Static/Instance Property Separation:** Intelligently separates static and instance properties into distinct sections, with automatic scope detection and fallback logic for accurate classification.
+- **🆕 Getter/Setter Pair Merging:** Automatically detects and merges getter/setter pairs into single table entries, displaying combined descriptions and access type indicators.
 - **🆕 Intelligent Constructor Detection:** Only displays the "Constructor" section when a class has explicit constructor documentation, avoiding empty constructor sections for classes without custom constructors.
 - **🆕 Field-Level JSDoc Support:** Properties table is populated directly from `@type` annotations on individual class fields, eliminating the need for redundant `@property` tags in class-level JSDoc.
 - **🆕 Clean Member Organization:** Properties are displayed in their own dedicated section, while the "Members" section can be configured to show only methods, avoiding duplication.
@@ -33,8 +35,10 @@
 The enhanced features of `qubit-jsdoc-theme` include:
 
 1. **Smart Properties Table**: Automatically generated from field-level `@type` annotations
-2. **Intelligent Constructor Detection**: Only shows constructor section when explicitly documented
-3. **Clean Organization**: Properties and methods are clearly separated
+2. **Static/Instance Property Separation**: Properties are automatically categorized and displayed in separate sections
+3. **Getter/Setter Pair Merging**: Related accessor methods are intelligently combined in the properties table
+4. **Intelligent Constructor Detection**: Only shows constructor section when explicitly documented
+5. **Clean Organization**: Properties and methods are clearly separated with enhanced categorization
 
 For the base theme features and styling, you can reference the original [clean-jsdoc-theme demo](https://ankdev.me/clean-jsdoc-theme/v4).
 
@@ -97,6 +101,13 @@ Here's how to document your JavaScript classes to take advantage of the enhanced
  * @author John Doe
  */
 class User {
+    /**
+     * Total number of users created
+     * @type {number}
+     * @static
+     */
+    static userCount = 0;
+
     /**
      * User's unique identifier
      * @type {string}
@@ -121,6 +132,24 @@ class User {
      */
     isActive;
 
+    /**
+     * Get user's full display information
+     * @type {string}
+     */
+    get displayInfo() {
+        return `${this.name} (${this.email})`;
+    }
+
+    /**
+     * Set user's full display information
+     * @type {string}
+     */
+    set displayInfo(value) {
+        const parts = value.split(' (');
+        this.name = parts[0];
+        this.email = parts[1]?.replace(')', '') || '';
+    }
+
     /**
      * Creates a new user instance
      * @param {string} name - The user's name
@@ -130,6 +159,7 @@ class User {
         this.name = name;
         this.email = email;
         this.isActive = true;
+        User.userCount++;
     }
 
     /**
@@ -144,9 +174,10 @@ class User {
 ```
 
 This will generate documentation with:
-- A dedicated "Properties" section showing all class properties in a table
-- A "Constructor" section (only if constructor has documentation)
-- A "Members" section for methods (properties are excluded to avoid duplication)
+- **Static Properties section**: Showing `userCount` and other static properties
+- **Instance Properties section**: Showing `id`, `name`, `email`, `isActive` and merged `displayInfo` (getter/setter)
+- **Constructor section**: Only displayed when constructor has documentation
+- **Members section**: For methods like `activate()` (properties are excluded to avoid duplication)
 
 ## Example JSDoc Config
 
@@ -706,6 +737,26 @@ Don't forget to add the following in your jsdoc config file, otherwise toc will
 
 ## Changelog
 
+### v1.5.0 (2025-01-XX)
+
+**Advanced Property Management & Enhanced Documentation Features**
+
+#### 🔧 New Features
+- **Static/Instance Property Separation**: Automatically separates static and instance properties into distinct sections with intelligent scope detection
+- **Getter/Setter Pair Merging**: Smart detection and merging of getter/setter pairs into unified table entries with combined descriptions
+- **Enhanced Scope Detection**: Improved logic for detecting property scope using JSDoc's built-in detection with fallback heuristics
+- **Access Type Indicators**: Clear visual indicators for property access types (property, getter, setter, getter/setter)
+
+#### 🛠️ Technical Improvements
+- **Advanced Template Logic**: Enhanced `container.tmpl` with sophisticated property categorization and merging algorithms
+- **Improved Properties Template**: Updated `properties.tmpl` to support separate rendering of static and instance properties
+- **Fallback Scope Detection**: Added longname pattern analysis for accurate scope detection when JSDoc's built-in detection fails
+- **Bilingual Section Headers**: Support for both English and Chinese section headers in property tables
+
+#### 📖 Documentation Updates
+- **Enhanced Usage Examples**: Updated examples to demonstrate static properties and getter/setter documentation
+- **Feature Documentation**: Comprehensive documentation for new property management features
+
 ### v1.4.0 (2025-01-XX)
 
 **Enhanced Mixin Documentation Support**

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@qubit-ltd/jsdoc-theme",
-    "version": "1.4.0",
+    "version": "1.5.0",
     "description": "A customized JSDoc theme based on clean-jsdoc-theme, enhanced with properties table and constructor detection features for Qubit projects.",
     "main": "publish.js",
     "author": "Haixing Hu (starfish.hu@gmail.com)",

package/tmpl/container.tmpl

@@ -152,18 +152,103 @@
         }
 
         if (allMembers && allMembers.length && allMembers.forEach) {
-            // Create a temporary properties array
-            var propertiesData = {
-                properties: allMembers.map(function(member) {
-                    return {
-                        name: member.name,
+            // Separate static and instance properties, merge getter/setter pairs
+            var staticProperties = {};
+            var instanceProperties = {};
+
+                                                                        allMembers.forEach(function(member) {
+                // Use JSDoc's built-in scope detection with fallback logic
+                // JSDoc sometimes misidentifies scope in mixin classes, so we add some heuristics
+                var isStatic = member.scope === 'static';
+
+                // Fallback: check longname pattern for static members (uses '.' separator)
+                // and instance members (uses '#' separator)
+                if (member.longname) {
+                    var hasStaticSeparator = member.longname.indexOf('.') > member.longname.lastIndexOf('#');
+                    var hasInstanceSeparator = member.longname.indexOf('#') > member.longname.lastIndexOf('.');
+
+                    if (hasStaticSeparator && !hasInstanceSeparator) {
+                        isStatic = true;
+                    } else if (hasInstanceSeparator && !hasStaticSeparator) {
+                        isStatic = false;
+                    }
+                }
+
+                var targetObj = isStatic ? staticProperties : instanceProperties;
+                var propName = member.name;
+
+                if (!targetObj[propName]) {
+                    targetObj[propName] = {
+                        name: propName,
                         type: member.type,
                         description: member.description || '',
                         nullable: member.nullable,
                         optional: member.optional,
-                        defaultvalue: member.defaultvalue
+                        defaultvalue: member.defaultvalue,
+                        isStatic: isStatic,
+                        hasGetter: false,
+                        hasSetter: false,
+                        getterDescription: '',
+                        setterDescription: ''
                     };
-                })
+                }
+
+                // Check if this is a getter or setter based on description or other indicators
+                var desc = (member.description || '').toLowerCase();
+                if (desc.indexOf('获取') === 0 || desc.indexOf('get') === 0) {
+                    targetObj[propName].hasGetter = true;
+                    targetObj[propName].getterDescription = member.description || '';
+                } else if (desc.indexOf('设置') === 0 || desc.indexOf('set') === 0) {
+                    targetObj[propName].hasSetter = true;
+                    targetObj[propName].setterDescription = member.description || '';
+                } else {
+                    // Regular property, use the description as is
+                    if (!targetObj[propName].description) {
+                        targetObj[propName].description = member.description || '';
+                    }
+                }
+            });
+
+            // Convert objects to arrays
+            var staticPropsArray = Object.keys(staticProperties).map(function(key) {
+                var prop = staticProperties[key];
+                // Combine getter/setter descriptions
+                if (prop.hasGetter && prop.hasSetter) {
+                    prop.description = prop.getterDescription + ' / ' + prop.setterDescription;
+                    prop.accessType = 'getter/setter';
+                } else if (prop.hasGetter) {
+                    prop.description = prop.getterDescription;
+                    prop.accessType = 'getter';
+                } else if (prop.hasSetter) {
+                    prop.description = prop.setterDescription;
+                    prop.accessType = 'setter';
+                } else {
+                    prop.accessType = 'property';
+                }
+                return prop;
+            });
+
+            var instancePropsArray = Object.keys(instanceProperties).map(function(key) {
+                var prop = instanceProperties[key];
+                if (prop.hasGetter && prop.hasSetter) {
+                    prop.description = prop.getterDescription + ' / ' + prop.setterDescription;
+                    prop.accessType = 'getter/setter';
+                } else if (prop.hasGetter) {
+                    prop.description = prop.getterDescription;
+                    prop.accessType = 'getter';
+                } else if (prop.hasSetter) {
+                    prop.description = prop.setterDescription;
+                    prop.accessType = 'setter';
+                } else {
+                    prop.accessType = 'property';
+                }
+                return prop;
+            });
+
+            // Create properties data with both static and instance properties
+            var propertiesData = {
+                staticProperties: staticPropsArray,
+                instanceProperties: instancePropsArray
             };
     ?>
         <h2 id="properties" class="subsection-title has-anchor"><?js= t('properties') ?></h2>

package/tmpl/properties.tmpl

@@ -1,109 +1,132 @@
 <?js
     var data = obj;
-    var props = data.subprops || data.properties;
-
-    /* sort subprops under their parent props (like opts.classname) */
-    var parentProp = null;
-    props.forEach(function(prop, i) {
-        if (!prop) { return; }
-        if ( parentProp && prop.name && prop.name.indexOf(parentProp.name + '.') === 0 ) {
-            prop.name = prop.name.substr(parentProp.name.length+1);
-            parentProp.subprops = parentProp.subprops || [];
-            parentProp.subprops.push(prop);
-            props[i] = null;
-        }
-        else {
-            parentProp = prop;
-        }
-    });
+    var self = this;
+
+    // Handle both old format (single properties array) and new format (static/instance separation)
+    var staticProps = data.staticProperties || [];
+    var instanceProps = data.instanceProperties || data.properties || [];
+
+    // Function to render a properties table
+    function renderPropertiesTable(props, title) {
+        if (!props || props.length === 0) return '';
+
+        /* sort subprops under their parent props (like opts.classname) */
+        var parentProp = null;
+        props.forEach(function(prop, i) {
+            if (!prop) { return; }
+            if ( parentProp && prop.name && prop.name.indexOf(parentProp.name + '.') === 0 ) {
+                prop.name = prop.name.substr(parentProp.name.length+1);
+                parentProp.subprops = parentProp.subprops || [];
+                parentProp.subprops.push(prop);
+                props[i] = null;
+            }
+            else {
+                parentProp = prop;
+            }
+        });
+
+        /* determine if we need extra columns, "attributes" and "default" */
+        props.hasAttributes = false;
+        props.hasDefault = false;
+        props.hasName = false;
+
+        props.forEach(function(prop) {
+            if (!prop) { return; }
+
+            if (prop.optional || prop.nullable) {
+                props.hasAttributes = true;
+            }
 
-    /* determine if we need extra columns, "attributes" and "default" */
-    props.hasAttributes = false;
-    props.hasDefault = false;
-    props.hasName = false;
+            if (prop.name) {
+                props.hasName = true;
+            }
 
-    props.forEach(function(prop) {
-        if (!prop) { return; }
+            if (typeof prop.defaultvalue !== 'undefined' && !data.isEnum) {
+                props.hasDefault = true;
+            }
+        });
 
-        if (prop.optional || prop.nullable) {
-            props.hasAttributes = true;
+        var html = '';
+        if (title) {
+            html += '<h3 class="subsection-title">' + title + '</h3>';
         }
 
-        if (prop.name) {
-            props.hasName = true;
+        html += '<div class="allow-overflow">';
+        html += '<table class="props">';
+        html += '<thead><tr>';
+
+        if (props.hasName) {
+            html += '<th>' + t('name') + '</th>';
         }
+        html += '<th>' + t('type') + '</th>';
 
-        if (typeof prop.defaultvalue !== 'undefined' && !data.isEnum) {
-            props.hasDefault = true;
+        if (props.hasAttributes) {
+            html += '<th>' + t('attributes') + '</th>';
         }
-    });
-?>
-<div class="allow-overflow">
-<table class="props">
-    <thead>
-    <tr>
-        <?js if (props.hasName) {?>
-        <th><?js= t('name') ?></th>
-        <?js } ?>
-
-        <th><?js= t('type') ?></th>
-
-        <?js if (props.hasAttributes) {?>
-        <th><?js= t('attributes') ?></th>
-        <?js } ?>
-
-        <?js if (props.hasDefault) {?>
-        <th><?js= t('default') ?></th>
-        <?js } ?>
-
-        <th class="last"><?js= t('description') ?></th>
-    </tr>
-    </thead>
-
-    <tbody>
-    <?js
-        var self = this;
+
+        if (props.hasDefault) {
+            html += '<th>' + t('default') + '</th>';
+        }
+
+        html += '<th class="last">' + t('description') + '</th>';
+        html += '</tr></thead><tbody>';
+
         props.forEach(function(prop) {
             if (!prop) { return; }
-    ?>
-
-        <tr>
-            <?js if (props.hasName) {?>
-                <td class="name"><code><?js= prop.name ?></code></td>
-            <?js } ?>
-
-            <td class="type">
-            <?js if (prop.type && prop.type.names) {?>
-                <?js= self.partial('type.tmpl', prop.type.names) ?>
-            <?js } ?>
-            </td>
-
-            <?js if (props.hasAttributes) {?>
-                <td class="attributes">
-                <?js if (prop.optional) { ?>
-                    &lt;optional><br>
-                <?js } ?>
-
-                <?js if (prop.nullable) { ?>
-                    &lt;nullable><br>
-                <?js } ?>
-                </td>
-            <?js } ?>
-
-            <?js if (props.hasDefault) {?>
-                <td class="default">
-                <?js if (typeof prop.defaultvalue !== 'undefined') { ?>
-                    <?js= self.htmlsafe(prop.defaultvalue) ?>
-                <?js } ?>
-                </td>
-            <?js } ?>
-
-            <td class="description last"><?js= prop.description ?><?js if (prop.subprops) { ?>
-                <h6>Properties</h6><?js= self.partial('properties.tmpl', prop) ?>
-            <?js } ?></td>
-        </tr>
-
-    <?js }); ?>
-    </tbody>
-</table>
-</div>
+
+            html += '<tr>';
+
+            if (props.hasName) {
+                var nameDisplay = prop.name;
+                if (prop.accessType && prop.accessType !== 'property') {
+                    nameDisplay += ' <em>(' + prop.accessType + ')</em>';
+                }
+                html += '<td class="name"><code>' + nameDisplay + '</code></td>';
+            }
+
+            html += '<td class="type">';
+            if (prop.type && prop.type.names) {
+                html += self.partial('type.tmpl', prop.type.names);
+            }
+            html += '</td>';
+
+            if (props.hasAttributes) {
+                html += '<td class="attributes">';
+                if (prop.optional) {
+                    html += '&lt;optional><br>';
+                }
+                if (prop.nullable) {
+                    html += '&lt;nullable><br>';
+                }
+                html += '</td>';
+            }
+
+            if (props.hasDefault) {
+                html += '<td class="default">';
+                if (typeof prop.defaultvalue !== 'undefined') {
+                    html += self.htmlsafe(prop.defaultvalue);
+                }
+                html += '</td>';
+            }
+
+            html += '<td class="description last">' + (prop.description || '');
+            if (prop.subprops) {
+                html += '<h6>Properties</h6>' + self.partial('properties.tmpl', prop);
+            }
+            html += '</td>';
+
+            html += '</tr>';
+        });
+
+        html += '</tbody></table></div>';
+        return html;
+    }
+?>
+
+<?js if (staticProps.length > 0) { ?>
+    <?js= renderPropertiesTable(staticProps, '静态属性') ?>
+<?js } ?>
+
+<?js if (instanceProps.length > 0) { ?>
+    <?js= renderPropertiesTable(instanceProps, staticProps.length > 0 ? '实例属性' : null) ?>
+<?js } ?>