WMarkDown

Documentación de Código

El módulo de Documentación de Código o Code Doc es un módulo que sirve para identificar elementos concretos dentro del código fuente del proyecto de forma genérica. Está basado en documentar funciones y métodos principalmente aunque permite más funciones que éstas. Las funciones y los métodos, en base a la filosofía de este módulo, están diseñadas en base a un entorno fuertemente tipado con estructuras de sobrecargas y argumentos opciones. Su estructura se basa en marcas que identifican las diferentes partes.

[[@ [String] WMarkDown.process(!String data, Integer lanuage = 1, ?String path = null)]]

[[@ [String] WMarkdown.analyse(!String data, Integer language = 1, Integer mode = 0, ?String path = null)]]

El módulo crearía una capa adaptada al espacio del párrafo el cual tendría el bloque de llamada explicado a nivel de código y una tabla con los argumentos definidos de una forma simplificada para ayudar en su comprensión.

La sintaxis es sencilla, parte de lo siguiente:

• Tipado de respuesta: Es un elemento opcional comprendido entre corchetes que determina el tipado de respuesta. Si no se especifica, por defecto será void (Vacío).
• Acceso: Es un elemento opcional que determina el acceso a dicho elemento, donde si no se nombra se entenderá como elemento público, pero sino, indicaría lo siguiente:
  • Privado: Determina que el elemento del que se habla tiene acceso únicamente privado y se representa mediante el caracter "!".
  • Protegido: Determina que el elemento del que se habla tiene acceso protegido por su herencia y se representa mediante el caracter "?".
• Espacio de nombres: Es un elemento opcional que determina el espacio de nombres para llegar hasta éste, ya sea por nombre de Clase, por el propio espacio de nombres, o ambos juntos como puede suceder en PHP.
• Ámbito: Es un elemento opcional que determina el la separación entre el espacio de nombres y el nombre del elemento se separan por un caracter el cual indica uno de estos dos casos.
  • Objeto: Se indica con un punto (".") e indica que parte de la creación de un objeto a partir de la clase que lo nombra. En caso de no haber nombre
  • Estático: Se indica con dos puntos (":") e indica que parte de la clase que lo nombra.
• Método o Elemento: Nombre del método o elemento al que se hace referencia.
• Argumentos: Bloque opcional que se especifica únicamente en caso de ser un método o una función, entre paréntesis tendrá los argumentos de entrada. Cada argumento tendría lo siguiente:
  • Obligatorio: El primer elemento es opcional e indica si es opcional u obligatorio donde si hay al inicio del argumento un cierre de exclamación ("!") indica que es obligatorio, sino nos indica que es opcional.
  • Nulleable: El segundo elemento es opcional e indica si es nulleable o no donde si hay al inicio del argumento un cierre de interrogación ("?") indica que es nulleable, sino, no admite valores nulos.
  • Tipado: El tercer elemento es obligatorio e indica el tipado del argumento.
  • Nombre: El cuarto elemento es obligatorio e indica el nombre del argumento.
  • Valor por defecto: El quinto elemento es opcional y especifica el valor por defecto que tiene ese argumento. Sólo se especifica para argumentos opcionales cuando éstos tienen un valor por defecto. Se identifica por ir separado con el signo igual ("=") del nombre hasta la coma que lo separa. En caso de ser un String, diccionario o Array se identifica su final con el cierre del mismo.
• Valor por defecto: Bloque opcional diseñado para valores de variables y constantes que representa su valor por defecto. Se distingue de los argumentos mediante la separación con el nombre del método con el caracter iguale ("=").

El Espacio de nombres y el Ámbito van juntos, es decir, si se especifican han de existir los dos, si no, no se ha de especificar ninguno de los dos.

Puede haber más de un tipado alternativo. Éstos se separan con el caracter tubería ("|").

Cara los tipados, el nombre que se le dé dependerá del desarrollador y del propio nombre de las clases de los que parten los posibles objetos, sin embargo, hay que destacar que se espera encapsulados entre diamantes en casos de ser Vectores o definición de diccionarios y/o objetos.

<!-- 
    Definidión de una variable que viene siendo un vector de Objetos cuyos 
    elementos pueden ser de cualquier tipado. 
-->
[[@ [Array<Object<String, Any>>] ejemplo]]

Cuando hablamos de variables o métodos y funciones que no tienen argumentos, la tabla de definición de argumentos no aparecerá, o en caso de ser alterado el CSS original del WMarkDown, saldrá vacía.

Para especificar valores nulos o cualquier valor aconsejamos, por mantener un estándar basado en JSDoc (No se sigue plenamente la filosofía de JSDoc, pero si se basa bastante en ésta) el uso de Null y Any consecutivamente. También destacar que Any no representa entre sus valores ni a Null ni a "undefined" en el caso de JavaScript.