dr-readme

Generador reutilizable de README para plugins y themes.

1. Qué hace

dr-readme es un plugin reutilizable para WordPress que genera y actualiza bloques de documentación dentro de un README.md.

Su función principal es recorrer un plugin o theme objetivo, detectar archivos y piezas de código relevantes, y construir un árbol contextualizado legible para humanos.

Actualmente está orientado a:

• archivos PHP
• archivos JS
• clases
• funciones
• métodos
• descripciones cortas extraídas de comentarios

El resultado puede mostrarse por consola o insertarse automáticamente dentro de un bloque concreto del README.md.

---

2. Para qué sirve

dr-readme sirve para mantener documentado un proyecto sin tener que reescribir manualmente la estructura del código cada vez que cambia.

Objetivos principales:

• tener un README.md siempre actualizado
• entender rápido la arquitectura de un plugin o theme
• ver clases, funciones y métodos de un vistazo
• reducir documentación manual repetitiva
• estandarizar la documentación entre distintos proyectos

La idea es que el sistema dr-readme viva como plugin independiente y pueda trabajar sobre cualquier plugin o theme usando --target.

---

3. Alcance de --target

El parámetro --target indica el directorio exacto sobre el que debe trabajar dr-readme.

Ejemplos:

wp dr-readme tree --target=$(pwd)
wp dr-readme update --target=$(pwd) --block=TREE
wp dr-readme update-all --target=$(pwd)

Si ejecutas esos comandos dentro de un plugin o theme, dr-readme trabajará solo sobre ese directorio.

Eso significa que:

no analiza otros plugins no analiza otros themes no modifica README.md fuera del target indicado no mezcla árboles de varios proyectos

El target define el alcance completo del análisis y de la actualización.

4. Cómo documentar clases, funciones y métodos

Para que el árbol contextualizado sea útil, las clases, funciones y métodos importantes deben llevar un comentario corto justo encima.

El comentario debe ser:

sobrio claro una sola línea útil pegado al elemento que describe

Ejemplo en PHP:

/**
 * resolve_url_request — Resuelve una petición basada en URL.
 */
public static function resolve_url_request(array $request) {
    ...
}

/**
 * DR_Readme_Manager — Gestiona la lectura y actualización del README.
 */
class DR_Readme_Manager {
    ...
}

/**
 * buildRequest — Construye la petición para dataserver.
 */
function buildRequest(data) {
    ...
}

La idea no es escribir documentación larga, sino dejar una intención clara y corta.

5. Qué comentarios reconoce

El formato histórico recomendado es:

/**
 * nombre_real — Descripción breve.
 */

También se aceptan docblocks convencionales y comentarios // asociados directamente en JavaScript. En un docblock convencional se utiliza como descripción la primera línea útil y se ignoran etiquetas como @param y @return.

Reglas del formato histórico:

1. el nombre debe coincidir con el nombre real de la clase,  función o método
2. se admite raya larga —, raya – o guion corto -
3. la descripción debe ser breve
4. el comentario debe estar justo encima del elemento
5. el formato debe ser limpio y consistente

Ejemplo válido:

/**
 * update_block — Sustituye un bloque marcado dentro del README.
 */
public function update_block($block_name, $content) {
    ...
}

Si una función o método no tiene comentario, aparece igualmente en el árbol, pero sin descripción asociada.

6. Cómo generar el árbol (tree)

El comando tree genera el árbol contextualizado del proyecto objetivo y lo imprime por consola.

Uso:

wp dr-readme tree --target=$(pwd)

Qué hace:

recorre el directorio indicado localiza archivos compatibles detecta clases, funciones y métodos extrae comentarios reconocibles construye una salida tipo árbol

Ejemplo típico:

• includes/api/class-public-api.php │ # DRADC_Dataserver_Public_API │ + get_data() │ │ # Devuelve datos del batch clásico. │ + get_big_product() │ │ # Devuelve un producto grande.

Este comando no modifica archivos. Solo muestra el árbol generado.

7. Cómo actualizar el bloque TREE

Si tu README.md contiene un bloque marcado para TREE, puedes actualizarlo automáticamente.

Uso:

wp dr-readme update --target=$(pwd) --block=TREE

Bloque esperado dentro de README.md:

Qué hace:

1. genera el árbol contextualizado
2. localiza el bloque TREE
3. sustituye su contenido
4. guarda el README.md

Esto permite regenerar la parte estructural del README sin tocar el resto del documento.

8. Cómo actualizar un solo bloque

dr-readme puede actualizar un bloque concreto del README.md usando --block.

Ejemplo actual:

wp dr-readme update --target=$(pwd) --block=TREE

La idea de este sistema es que cada bloque del README pueda actualizarse de forma independiente.

Por ejemplo, en el futuro podrían existir bloques como:

TREE COMMANDS STRUCTS FLOWS

Cada bloque tendría sus propios marcadores:

Ahora mismo el bloque soportado principal es TREE.

9. Cómo actualizar todos los bloques (update-all)

El comando update-all está pensado para actualizar todos los bloques soportados del README.md de una sola vez.

Uso:

wp dr-readme update-all --target=$(pwd)

Qué hace:

localiza el README.md del target genera los contenidos necesarios actualiza todos los bloques soportados

Actualmente el uso principal es actualizar TREE, pero la idea de update-all es dejar preparado el sistema para crecer sin cambiar la forma de trabajar.

Es el comando más cómodo cuando quieres dejar el README entero al día.

10. Qué no hace / limitaciones actuales

dr-readme no pretende entender todo el proyecto como lo haría un analizador semántico completo.

Limitaciones actuales:

se centra en PHP y JS no interpreta lógica profunda no reconstruye dependencias complejas entre archivos no entiende intención si no hay comentario claro no documenta automáticamente arquitectura implícita no sustituye documentación humana de alto nivel necesita que los comentarios sigan un patrón reconocible puede listar elementos sin descripción si no están comentados

También conviene tener presente que:

si el README.md no tiene los marcadores esperados, el bloque no podrá actualizarse correctamente si un proyecto tiene clases repetidas, nombres ambiguos o comentarios inconsistentes, el árbol será menos útil si varios plugins embeben versiones antiguas del sistema readme con las mismas clases, puede haber conflictos si no se desactivan 11. Ejemplos de uso Mostrar el árbol del plugin o theme actual wp dr-readme tree --target=$(pwd) Actualizar solo el bloque TREE wp dr-readme update --target=$(pwd) --block=TREE Actualizar todos los bloques soportados wp dr-readme update-all --target=$(pwd) Usarlo sobre un plugin concreto wp dr-readme tree --target=wp-content/plugins/[plugin-dir] Usarlo sobre un theme concreto wp dr-readme tree --target=wp-content/themes/[theme-dir]

Ejemplo de comentario válido en PHP

/**
 * get_data — Devuelve datos del batch clásico.
 */
public static function get_data(array $request) {
    ...
}
Ejemplo de comentario válido en JS
/**
 * getPanelSkeleton — Devuelve el skeleton apropiado del panel.
 */
getPanelSkeleton(request) {
    ...
}

├── dr-readme.php ├── includes │ ├── class-dr-readme-plugin.php │ │ + DR_Readme_Plugin() │ │ │ # Inicializa los componentes principales de dr-readme. │ │ + init() │ │ │ # Inicializa el plugin. │ │ + load_core_files() │ │ │ # Carga los archivos base del sistema README. │ │ + load_cli_files() │ │ │ # Carga los comandos WP-CLI del plugin. │ ├── cli │ │ └── class-dr-readme-cli.php │ │ + DR_Readme_CLI() │ │ │ # Gestiona los comandos WP-CLI de dr-readme. │ │ + tree() │ │ │ # Genera el árbol contextualizado del target. │ │ + update() │ │ │ # Actualiza un bloque concreto del README del target. │ │ + update_all() │ │ │ # Actualiza todos los bloques soportados del README. │ │ + validate_target() │ │ │ # Valida y normaliza el directorio objetivo. │ └── core │ ├── class-dr-readme-comment-parser.php │ │ + DR_Readme_Comment_Parser() │ │ │ # Extrae descripciones cortas desde comentarios reconocibles. │ │ + extract_description() │ │ │ # Extrae el resumen útil de un comentario asociado. │ │ + parse_description_map() │ │ │ # Extrae descripciones cortas indexadas por nombre. │ ├── class-dr-readme-file-scanner.php │ │ + DR_Readme_File_Scanner() │ │ │ # Escanea los archivos relevantes del target. │ │ + scan() │ │ │ # Devuelve los archivos relevantes del target. │ │ + normalize_target() │ │ │ # Normaliza la ruta target. │ │ + is_ignored_path() │ │ │ # Indica si una ruta debe ignorarse. │ ├── class-dr-readme-manager.php │ │ + DR_Readme_Manager() │ │ │ # Gestiona la lectura y actualización del README. │ │ + update_block() │ │ │ # Sustituye o crea un bloque marcado dentro del README. │ └── class-dr-readme-tree-generator.php │ + DR_Readme_Tree_Generator() │ │ # Genera un árbol contextualizado estable del target. │ + generate() │ │ # Escanea y genera el árbol real del target. │ + to_relative_path() │ │ # Convierte una ruta absoluta en una ruta relativa segura. │ + insert_path() │ │ # Inserta un archivo y sus directorios dentro del árbol. │ + render_tree() │ │ # Renderiza recursivamente los nodos con conectores visuales. │ + render_file_members() │ │ # Añade los miembros detectados debajo de un archivo. │ + parse_members() │ │ # Extrae miembros PHP o JavaScript en orden de aparición. │ + parse_php_members() │ │ # Analiza clases, métodos y funciones PHP mediante tokens. │ + parse_js_members() │ │ # Analiza clases, métodos y funciones JavaScript nombradas. │ + js_class_ranges() │ │ # Localiza los límites estructurales de las clases JavaScript. │ + is_direct_js_class_member() │ │ # Comprueba si una declaración pertenece directamente a una clase. │ + next_token_name() │ │ # Obtiene el nombre declarado después de un token PHP. │ + previous_significant_is() │ │ # Compara el token PHP significativo anterior. │ + member() │ │ # Construye la representación normalizada de un miembro. │ + dedupe_members() │ │ # Elimina miembros repetidos conservando el orden original. └── tests └── run.php