Documentacion

Ver en Git

---

Documentación de código

El proyecto maneja dos tipos de documentación con propósitos diferentes:

1. Documentación interna

Propósito: Para el equipo de desarrollo interno

Ubicación:

• Documentación general para explicar un feature y su arquitectura en la carpeta docs
• Docstrings de funciones/clases internas
• Comentarios en el código (solo en casos necesarios, el codigo debe ser autoexplicativo!!)

Nota importante: Todo lo que sea documentado en un docstring luego del seprador --- será parseado para la documentación OpenAPI/Swagger y esta puede ser pública tener mucho cuidado con lo que se documenta allí. Mas información debajo en la sección "Documentación Externa"

Características:

• Idioma: Español o inglés
• Audiencia: Desarrolladores del equipo
• Nivel de detalle: Alto - incluir toda la información técnica necesaria

Qué incluir:

• Detalles de implementación
• Nombres de tablas y campos de BD
• Lógica de negocio compleja
• Decisiones técnicas y por qué se tomaron
• TODOs y deuda técnica
• Referencias a otras partes del código
• Casos edge y validaciones específicas

Ejemplo en función interna:

def delete_fields(field_ids):
    """
    Realiza la baja lógica de lotes estableciendo fecha_fin.
    
    Implementación:
    - Actualiza tabla 'lotes' con fecha_fin = now()
    - Inserta registro en 'lotes_eliminados' para tracking de Sentinel
    - Acepta int o Iterable de field_ids
    
    :param int|Iterable field_ids: ID(s) de lotes a eliminar
    :return: None
    
    Nota: No valida permisos - debe hacerse antes de llamar esta función
    """

Ejemplo en endpoint (clase API):

class DeleteFieldsAPI(AuraResource):
    """
    API para eliminación de lotes (fields).
    
    Implementación:
    - Recibe field_uuid y lo convierte a field_id interno
    - Realiza baja lógica estableciendo fecha_fin en tabla 'lotes'
    - Valida permisos mediante dos mecanismos:
      1. Validación especial para admins de escritorio 66
      2. Validación estándar usando sistema de permisos (requiere permiso LOB)
    - Aplica límite de 5 eliminaciones diarias para usuarios gratuitos
    
    Tablas involucradas:
    - lotes: se actualiza fecha_fin
    - lotes_eliminados: se inserta registro para Sentinel
    - permisos: validación de permisos (id_rol=1 es owner)
    """

2. Documentación externa (API Reference)

Propósito: Para usuarios externos que consumen la API. Esta documentación será parte de los docs para desarrolladores externos, no debemos exponer información interna. Las explicaciones deben ser genéricas.

Ubicación: Docstrings en métodos de endpoints, DESPUÉS del separador --- (formato OpenAPI 3.0 YAML)

Características:

• Idioma: Inglés
• Audiencia: Desarrolladores externos
• Tono: Claro, directo y profesional
• Contenido: Qué hace el endpoint desde la perspectiva del usuario

Qué incluir:

• Descripción funcional simple
• Requisitos de permisos (sin detalles técnicos)
• Limitaciones relevantes (rate limits, cuotas)
• Parámetros con UUIDs cuando sea posible
• Ejemplos de request/response
• Códigos de error con mensajes claros
• Tag public_api: necesario para que el endpoint aparezca en el Swagger público, si se omite la API será interna/privada y no se publica a developers externos

Qué evitar:

• ❌ Detalles de implementación interna ("sets fecha_fin", "logical deletion")
• ❌ Referencias a código interno o nombres de tablas
• ❌ Menciones a APIs deprecadas o legacy
• ❌ Jerga técnica innecesaria

Ejemplo completo (documentación interna + externa):

@exception_handler
def delete(self):
    """
    DOCUMENTACIÓN INTERNA (para el equipo):
    
    Implementación:
    - Convierte field_uuid a field_id usando get_field_id_by_uuid()
    - Valida permisos: admins de escritorio 66 o permiso LOB
    - Verifica límite de 5 eliminaciones/día para usuarios gratuitos
    - Excepción: usuarios que excedieron cuota pueden eliminar
    - Llama a delete_fields() que hace UPDATE lotes SET fecha_fin
    - Registra evento en aura_events
    
    Códigos de error:
    - code=2: Sin permiso LOB
    - code=4: Límite de eliminaciones alcanzado
    
    ---
    DOCUMENTACIÓN PÚBLICA (OpenAPI - para usuarios externos):
    
    summary: Delete Field
    description: |
      Deletes a field from your account. You must have owner permissions to delete a field.
      Note: Free tier users have a daily limit on field deletions.
    tags:
      - Fields
      - public_api
    security:
      - bearerAuth: []
    requestBody:
      required: true
      content:
        application/json:
          schema:
            type: object
            required:
              - field_uuid
            properties:
              field_uuid:
                type: string
                format: uuid
                description: Field UUID to delete
                example: 550e8400-e29b-41d4-a716-446655440000
    responses:
      200:
        description: Field deleted successfully
        content:
          application/json:
            schema:
              type: object
              properties:
                info:
                  type: string
                  example: Field deleted successfully
      403:
        description: Insufficient permissions or deletion limit reached
        content:
          application/json:
            schema:
              type: object
              properties:
                code:
                  type: integer
                  enum: [2, 4]
                info:
                  type: string
    """

Nota importante: El separador --- divide la documentación interna (arriba) de la pública (abajo). Solo lo que está después del --- se expone en Swagger/OpenAPI.