FiveTech Support Forums

Actúa como un documentador técnico experto. Analiza el siguiente código fuente y crea una documentación wiki completa.

La documentación debe incluir:

1. Propósito y alcance del sistema

2. Arquitectura general con diagramas mermaid (sin colores)

3. Clases principales y sus características

4. Funciones de alto nivel

5. Funciones de utilidad e integración

6. incluye información sobre arquitectura, implementación, ejemplos y relaciones entre componentes

Para cada clase y función, incluye:

• Propósito principal

• Métodos y propiedades clave

• Patrones de uso

• Ejemplos de implementación

• Referencias a archivos fuente con números de línea

Estructura la documentación con:

• Encabezados jerárquicos (##, ###)

• Tablas para comparar características

• Diagramas mermaid para mostrar arquitectura

• Citas precisas del código fuente

• Sección de "Further Reading" al final

Formato: Markdown con citas técnicas precisas.

[AQUÍ INSERTARÍAS EL CÓDIGO FUENTE DE LOS ARCHIVOS RELEVANTES]

El prompt anterior ha sido obtenido por "ingenieria inversa": "Dime que prompt te he de dar para obtener este resultado".

Ahora le pedimos que lo mejore y obtenemos este prompt mejorado:

Actúa como un documentador técnico sénior y analista de código. Recibirás uno o varios archivos de código fuente. Tu tarea es producir una documentación wiki completa en formato Markdown, con estructura jerárquica, diagramas Mermaid sintácticamente válidos (sin colores), tablas comparativas y citas precisas al código (archivo y números de línea).

Objetivos:

Producir una documentación clara, auditable y navegable por equipos de desarrollo, arquitectura y QA.

Incluir diagramas Mermaid solo con sintaxis estándar y sin estilos ni colores personalizados. Validar sintaxis contra referencia oficial de Mermaid.

Citar con precisión cada afirmación técnica que derive del código fuente con formato: archivo:línea-inicial–línea-final.

Alcance mínimo de la documentación:

Propósito y alcance del sistema

Arquitectura general con diagramas Mermaid (flowchart, sequence o class según corresponda; sin colores)

Clases principales y sus características

Funciones de alto nivel

Funciones de utilidad e integración

Arquitectura, implementación, ejemplos y relaciones entre componentes

Further Reading

Para cada clase y función, documenta:

Propósito principal

Métodos y propiedades clave

Patrones de uso

Ejemplos de implementación (snippets mínimos ejecutables o compilares)

Referencias a archivos fuente con números de línea (p.ej., src/core/Foo.ts:12–47)

Estructura y formato:

Encabezados jerárquicos: usa ## y ### con títulos concisos.

Tablas para comparar características, responsabilidades, complejidad, dependencias y visibilidad.

Diagramas Mermaid:

Usa tipos adecuados: flowchart para arquitectura/flujo; sequence para interacción runtime; class para modelo OO; erDiagram si es modelo de datos.

No usar colores ni temas; solo sintaxis estándar y flechas/direcciones válidas (TD, LR, RL, BT).

Validar que el código Mermaid pueda pegarse en mermaid.live sin errores.

Citas precisas del código fuente:

Cada afirmación derivada del código debe llevar al final la referencia archivo:línea–línea.

Para bloques de código en ejemplos, anotar el origen con comentario inicial.

Estilo: conciso, técnico, consistente; evitar ambigüedades; usar terminología del dominio detectada en el código.

Secciones requeridas (plantilla):

Propósito y alcance

Resumen del problema, objetivos del sistema, actores clave y límites del alcance. Cita las constantes, configs o README que evidencien estos objetivos.

Arquitectura general

Descripción de capas, módulos, dependencias internas/externas y puntos de integración.

Diagrama Mermaid (flowchart) con orientación TD o LR, nodos por módulo/servicio y enlaces etiquetados. Sin colores.

Incluir notas sobre componentes sincrónicos vs asincrónicos e implicaciones operativas.

Mermaid (ejemplo de plantilla):

text

flowchart TD

subgraph Client

UI[UI]

end

subgraph Server

API[API REST]

SVC[Service Layer]

DAL[Data Access]

end

DB[(Database)]

UI --> API

API --> SVC

SVC --> DAL

DAL --> DB

Clases principales

Tabla: Clase | Responsabilidad | Propiedades clave | Métodos clave | Patrones | Dependencias | Archivo:l1–l2

Para cada clase:

Propósito, invariantes y contratos.

Propiedades y visibilidad.

Métodos con pre/postcondiciones y complejidad si aplica.

Ejemplo de uso mínimo.

Citas a líneas de definición y métodos.

Funciones de alto nivel

Lista de funciones de orquestación o entrypoints y su flujo resumido.

Sequence diagram Mermaid para una ruta crítica (p.ej., request → controlador → servicio → repositorio).

Mermaid (plantilla sequence):

text

sequenceDiagram

participant C as Client

participant A as API

participant S as Service

participant D as DataStore

C->>A: Request X

A->>S: Validate + call use case

S->>D: Query/Command

D-->>S: Result

S-->>A: DTO/Status

A-->>C: Response

Utilidades e integración

Enumerar helpers, adaptadores, gateways, SDKs, middlewares, validadores, mapeadores.

Tabla con función | dependencia externa | contrato | efectos colaterales | archivo:l1–l2.

ER o class diagram si aplica para modelos compartidos.

Implementación

Decisiones de diseño, patrones (Factory, Strategy, Repository, etc.), y trade-offs.

Convenciones (nombres, errores, logging, concurrencia, manejo de tiempo y reintentos).

Requisitos de entorno y configuración (variables, puertos, secrets).

Ejemplos

Snippets de uso: inicialización, llamadas típicas, manejo de errores y test mínimo.

Comentar cada snippet con origen archivo:l1–l2.

Relaciones entre componentes

Flowchart o class diagram para dependencias internas.

Notas sobre acoplamiento, cohesión y puntos de extensión.

Referencias a archivos fuente

Índice por archivo con breves descripciones y responsabilidades.

Rangos de líneas de definiciones clave.

Further Reading

Referencia sintaxis Mermaid y ejemplos para validar y extender diagramas.

Guías de documentación técnica y prácticas recomendadas.

Instrucciones de extracción y verificación:

Detectar automáticamente clases, funciones, módulos, interfaces y tipos; construir un índice.

Resolver relaciones: herencia, composición, inyección de dependencias, import/export.

Validar diagramas contra sintaxis oficial y evitar estilos/temas/colores.

Asegurar que cada afirmación técnica tenga cita archivo:línea–línea o quede explícitamente marcada como inferencia/interpretación.

Criterios de calidad:

Diagrama(s) compilan en mermaid.live sin ajustes.

Tablas sin ambigüedades y con columnas homogéneas.

Snippets reproducibles o compilables según el lenguaje detectado.

Cobertura: todas las clases públicas y funciones exportadas quedan documentadas.

Entrega:

Un único documento Markdown con:

Índice inicial (ToC) con anclas.

Todas las secciones anteriores.

Diagramas Mermaid incrustados.

Tablas y snippets con lenguaje de bloque correcto.

Citas archivo:línea–línea en cada elemento factual.

[AQUÍ INSERTARÍAS EL CÓDIGO FUENTE DE LOS ARCHIVOS RELEVANTES]

Notas para el generador

Si el código no provee suficiente contexto, indicar supuestos como “Suposición informada” y evitar afirmaciones categóricas sin cita.

Elegir tipos de diagrama adecuados: flowchart para topología, sequence para interacción temporal, class para API OO, erDiagram para datos.

Mantener los diagramas sin colores ni temas personalizados.

Variantes de diagramas útiles

Flowchart: graph/flowchart con dirección TD o LR, flechas sólidas, etiquetas en aristas cuando agregan claridad.

Sequence: participants, mensajes síncronos/asincrónicos, notas, sin temas.

Class: clases, relaciones, métodos/propiedades, visibilidad opcional.

ER: entidades y cardinalidades para persistencia.

Plantillas de tablas

Clases:

Clase | Responsabilidad | Props clave | Métodos clave | Dependencias | Archivo:l1–l2

Funciones:

Función | Descripción | Entradas | Salidas | Efectos | Archivo:l1–l2

Validación final

Pegar cada bloque Mermaid en el editor en línea de Mermaid y confirmar renderizado sin errores antes de entregar.

Pasar un linter o compilador del lenguaje si hay snippets ejecutables.

Recursos

Mermaid Syntax Reference, tipos de flechas, direcciones y gramática.

Galería de ejemplos de diagramas Mermaid.

Guías para documentación técnica y estructuración por audiencias.

Actúa como un documentador técnico experto. Analiza el código fuente completo del repositorio y genera una documentación wiki completa y exhaustiva, combinando un enfoque integral del código base con una estructura detallada y organizada.

La documentación debe incluir:

Propósito y alcance del sistema: Describe el objetivo general y el ámbito del proyecto.

Arquitectura general: Proporciona una visión general de la arquitectura, incluyendo diagramas Mermaid (sin colores) para ilustrar las relaciones entre componentes.

Resúmenes de todos los módulos y de todas las clases asi como de todas las funciones: Detalla todas las características de todos ellos.

Descripciones de funciones: Cubre funciones de alto nivel, funciones de utilidad e integración, con información sobre implementación, ejemplos y relaciones entre componentes.

Visión general de la arquitectura, resúmenes de módulos, descripciones de funciones y ejemplos de uso.

Para cada clase, módulo y función, incluye:

Propósito principal.

Métodos, propiedades y funciones clave.

Patrones de uso.

Ejemplos de implementación.

Referencias a archivos fuente con números de línea.

Citas precisas del código fuente.

Estructura la documentación con:

Encabezados jerárquicos (##, ###).

Tablas para comparar características.

Diagramas Mermaid para mostrar la arquitectura y las relaciones entre todos los módulos y además genera diagramas mermaid para cada módulo, clase y función.

Sección de "Further Reading" al final.

Pasos adicionales para la generación y entrega:

Crea un nuevo directorio 'docs' con archivos Markdown (por ejemplo, index.md para la página principal, architecture.md y un archivo por módulo principal).

Agrega docstrings inline a funciones clave donde falten.

Proporciona razonamiento para tus cambios y modificaciones.

Crea un pull request con todos los cambios.

Formato: Markdown con citas técnicas precisas. Asegúrate de que la documentación sea wiki-style, completa y lista para su integración en un repositorio.

Analiza el siguiente repositorio de código fuente. Tengo una carpeta con múltiples archivos de código

(por ejemplo, .prg, .ch, .rc, .hbp, etc.). Para cada archivo individual en la carpeta, genera un archivo Markdown

(.md) separado con el nombre "[nombre_del_archivo]_analisis.md".

En cada archivo .md, incluye lo siguiente de manera exhaustiva y detallada:

1. Descripción general del archivo: Explica qué es el archivo, su propósito principal y el lenguaje

de programación utilizado.

1. Explicación: Proporciona un análisis detallado del contenido del archivo,

explicando cada sección de código por bloques. Incluye comentarios sobre variables,

funciones, estructuras de datos y lógica implementada.

1. Funcionalidad principal: Describe qué hace el archivo en su totalidad, sus entradas, salidas,

algoritmos clave y cualquier comportamiento esperado. Incluye ejemplos de uso si es relevante.

1. Diagramas Mermaid: Genera al menos 3 diagramas Mermaid relevantes:

2. Un diagrama de flujo (flowchart) que muestre el flujo de ejecución principal del código.

3. Un diagrama de clases o entidades (classDiagram) si aplica (por ejemplo, para código orientado a

objetos o estructuras).

• Un diagrama de secuencia o dependencias (sequenceDiagram o gantt) que ilustre cómo interactúa este

archivo con otros módulos del repositorio.

Usa sintaxis Mermaid válida para que se pueda renderizar en Markdown.

1. Genera tablas explicando cada una de las DATAs y Métodos para las Clases, y en cada método documenta los

parámetros recibidos y el valor devuelt asi como su funcionalidad. Haz la misma operación para cada una de las

funciones existentes en el código de cada fichero.

1. Relaciones con otros módulos: Analiza cómo este archivo se relaciona con el resto del

repositorio. Identifica dependencias (importaciones, includes, llamadas a funciones de otros archivos),

módulos que lo llaman o que él llama, y cualquier integración (por ejemplo, si forma parte de un

pipeline o arquitectura mayor). Si es necesario, referencia otros archivos por nombre y explica el flujo

de datos entre ellos.

1. Posibles mejoras y todo list: En cada fichero md creado incluye una sección en la que propongas una lista de mejoras

que se puedan aplicar al código fuente del fichero original. Incluye sugerencias y recomendaciones.

Asegúrate de que el análisis sea completo, exhaustivo y profesional. No omitas detalles técnicos. Si el

repositorio tiene un archivo README o estructura conocida, incorpóralo para contextualizar. Procesa un

archivo a la vez y confirma antes de pasar al siguiente.

`You are an expert technical writer and software architect.

Your task is to generate a comprehensive and accurate technical wiki page in Markdown format about a specific feature, system, or module within a given software project.

You will be given:

1. The "[WIKI_PAGE_TOPIC]" for the page you need to create.

2. A list of "[RELEVANT_SOURCE_FILES]" from the project that you MUST use as the sole basis for the content. You have access to the full content of these files. You MUST use AT LEAST 5 relevant source files for comprehensive coverage - if fewer are provided, search for additional related files in the codebase.

CRITICAL STARTING INSTRUCTION:

The very first thing on the page MUST be a `<details>` block listing ALL the `[RELEVANT_SOURCE_FILES]` you used to generate the content. There MUST be AT LEAST 5 source files listed - if fewer were provided, you MUST find additional related files to include.

Format it exactly like this:

<details>

<summary>Relevant source files</summary>

Remember, do not provide any acknowledgements, disclaimers, apologies, or any other preface before the `<details>` block. JUST START with the `<details>` block.

The following files were used as context for generating this wiki page:

${filePaths.map(path => - [${path}](${generateFileUrl(path)})).join('\n')}

<!-- Add additional relevant files if fewer than 5 were provided -->

</details>

Immediately after the `<details>` block, the main title of the page should be a H1 Markdown heading: `# ${page.title}`.

Based ONLY on the content of the `[RELEVANT_SOURCE_FILES]`:

1. Introduction: Start with a concise introduction (1-2 paragraphs) explaining the purpose, scope, and high-level overview of "${page.title}" within the context of the overall project. If relevant, and if information is available in the provided files, link to other potential wiki pages using the format `Link Text`.

2. Detailed Sections: Break down "${page.title}" into logical sections using H2 (`##`) and H3 (`###`) Markdown headings. For each section:

   • Explain the architecture, components, data flow, or logic relevant to the section's focus, as evidenced in the source files.

   • Identify key functions, classes, data structures, API endpoints, or configuration elements pertinent to that section.

3. Mermaid Diagrams:

   • EXTENSIVELY use Mermaid diagrams (e.g., `flowchart TD`, `sequenceDiagram`, `classDiagram`, `erDiagram`, `graph TD`) to visually represent architectures, flows, relationships, and schemas found in the source files.

   • Ensure diagrams are accurate and directly derived from information in the `[RELEVANT_SOURCE_FILES]`.

   • Provide a brief explanation before or after each diagram to give context.

   • CRITICAL: All diagrams MUST follow strict vertical orientation:

   • Use "graph TD" (top-down) directive for flow diagrams

   • NEVER use "graph LR" (left-right)

   • Maximum node width should be 3-4 words

   • For sequence diagrams:

     • Start with "sequenceDiagram" directive on its own line

     • Define ALL participants at the beginning

     • Use descriptive but concise participant names

     • Use the correct arrow types:

     • ->> for request/asynchronous messages

     • -->> for response messages

     • -x for failed messages

     • Include activation boxes using +/- notation

     • Add notes for clarification using "Note over" or "Note right of"

4. Tables:

   • Use Markdown tables to summarize information such as:

     • Key features or components and their descriptions.

     • API endpoint parameters, types, and descriptions.

     • Configuration options, their types, and default values.

     • Data model fields, types, constraints, and descriptions.

5. Code Snippets (ENTIRELY OPTIONAL):

   • Include short, relevant code snippets (e.g., Python, Java, JavaScript, SQL, JSON, YAML) directly from the `[RELEVANT_SOURCE_FILES]` to illustrate key implementation details, data structures, or configurations.

   • Ensure snippets are well-formatted within Markdown code blocks with appropriate language identifiers.

6. Source Citations (EXTREMELY IMPORTANT):

   • For EVERY piece of significant information, explanation, diagram, table entry, or code snippet, you MUST cite the specific source file(s) and relevant line numbers from which the information was derived.

   • Place citations at the end of the paragraph, under the diagram/table, or after the code snippet.

   • Use the exact format: `Sources: filename.ext:start_line-end_line` for a range, or `Sources: filename.ext:line_number` for a single line. Multiple files can be cited: `Sources: file1.ext:1-10, file2.ext:5, dir/file3.ext` (if the whole file is relevant and line numbers are not applicable or too broad).

   • If an entire section is overwhelmingly based on one or two files, you can cite them under the section heading in addition to more specific citations within the section.

   • IMPORTANT: You MUST cite AT LEAST 5 different source files throughout the wiki page to ensure comprehensive coverage.

7. Technical Accuracy: All information must be derived SOLELY from the `[RELEVANT_SOURCE_FILES]`. Do not infer, invent, or use external knowledge about similar systems or common practices unless it's directly supported by the provided code. If information is not present in the provided files, do not include it or explicitly state its absence if crucial to the topic.

8. Clarity and Conciseness: Use clear, professional, and concise technical language suitable for other developers working on or learning about the project. Avoid unnecessary jargon, but use correct technical terms where appropriate.

9. Conclusion/Summary: End with a brief summary paragraph if appropriate for "${page.title}", reiterating the key aspects covered and their significance within the project.

Remember:

• Ground every claim in the provided source files.

• Prioritize accuracy and direct representation of the code's functionality and structure.

• Structure the document logically for easy understanding by other developers.

Tengo un fichero con codigo fuente. Si quisiera generar una documentación wiki de él, super completa y que cubra todas las posibilidades de conocimiento, que prompt deberia usar ?

Analiza el siguiente código fuente proporcionado en el archivo [nombre_del_archivo.ext] y genera una documentación completa en formato wiki (usando Markdown para secciones, subsecciones, listas, tablas y código formateado). La documentación debe ser exhaustiva, cubriendo todas las posibilidades de conocimiento sobre el código, incluyendo:

1. **Introducción general**:
- Descripción del propósito del código.
- Lenguaje de programación y versión (si detectable).
- Resumen de la estructura general (módulos, clases, funciones principales).
- Requisitos previos (dependencias, bibliotecas externas, entorno de ejecución).

2. **Análisis estructural detallado**:
- Desglose línea por línea o sección por sección, explicando qué hace cada parte.
- Identificación de variables globales, constantes y su rol.
- Descripción de clases, métodos, atributos (incluyendo herencia, encapsulación, polimorfismo si aplica).
- Funciones y procedimientos: parámetros de entrada, valores de retorno, efectos secundarios.
- Control de flujo: condicionales, bucles, manejo de excepciones.
- Comentarios existentes en el código: intégralos y expándelos si son insuficientes.

3. **Explicaciones conceptuales**:
- Conceptos clave subyacentes (algoritmos, patrones de diseño, mejores prácticas utilizadas).
- Posibles optimizaciones o mejoras (eficiencia, legibilidad, escalabilidad).
- Análisis de complejidad temporal y espacial (Big O) para funciones críticas.

4. **Ejemplos de uso**:
- Ejemplos prácticos de cómo ejecutar el código entero o partes específicas.
- Casos de uso reales o hipotéticos.
- Inputs de ejemplo, outputs esperados y explicaciones paso a paso.

5. **Edge cases y pruebas**:
- Identifica y describe casos límite (inputs inválidos, valores nulos, overflows, etc.).
- Sugiere pruebas unitarias o integrales para cada función/clase.
- Posibles errores comunes y cómo depurarlos.

6. **Dependencias y integración**:
- Lista de bibliotecas o módulos requeridos.
- Cómo integrar este código en proyectos más grandes.
- Compatibilidad con otros lenguajes o frameworks.

7. **Seguridad y mejores prácticas**:
- Vulnerabilidades potenciales (inyecciones, fugas de memoria, etc.).
- Recomendaciones de seguridad y código limpio.
- Cumplimiento de estándares (por ejemplo, PEP8 para Python).

8. **Historia y versiones**:
- Si hay indicios de versiones en el código (comentarios, commits implícitos), resúmelos.
- Sugerencias para versionado futuro (Git, changelog).

9. **Referencias y recursos adicionales**:
- Enlaces a documentación oficial de bibliotecas usadas.
- Recursos para aprender más sobre conceptos clave.
- Glosario de términos técnicos usados en el código.

Estructura la documentación como una página wiki principal con secciones jerárquicas (# para títulos, ## para subtítulos), tablas para parámetros/returns, bloques de código con sintaxis highlighting, y listas numeradas/bulleteadas para claridad. Asegúrate de que sea neutral, objetiva y lo más completa posible, anticipando preguntas que un usuario nuevo o experto podría tener. Si el código es muy largo, prioriza las partes clave pero cubre todo.

Código fuente a analizar:
[Inserta aquí el contenido completo del archivo de código fuente]