5 formas de documentar un modelo de Simulink

A menudo, cuando se abre un modelo de Simulink^® antiguo propio o uno desarrollado por un colega, no resulta fácil entender cómo funciona. Una documentación adecuada puede resultar muy útil en estos casos. También puede aumentar la productividad y facilitar la colaboración entre equipos.

Existen muchas formas de documentar un modelo de Simulink. Este artículo presenta cinco opciones, desde descripciones generales del modelo y notas rápidas en el área de diseño hasta documentación más detallada de modelos y bloques. Para ilustrar cada método, utilizaremos el modelo de vehículo de Simulink que se muestra en la Figura 1.

Especificación y visualización de información del modelo

El primer paso es proporcionar una descripción general. Puede ver y editar la propiedad Description del modelo en la vista de Property Inspector (Figura 2) o haciendo clic con el botón secundario en el área de diseño y seleccionando Model Properties. Para ver la descripción del modelo, introduzca help seguido del nombre del modelo en la línea de comandos de MATLAB^®.

La pestaña Info de Property Inspector también resume el historial del modelo, como las modificaciones, la versión y la fecha en que se guardó por última vez.

Anotación del modelo

Agregar anotaciones es otra forma de mejorar la legibilidad y la claridad del diseño. Las anotaciones son elementos visuales que permiten agregar notas y texto explicativo rápidamente. Utilice la paleta o haga doble clic en el área de diseño y seleccione Create Annotation para crear combinaciones de texto, imágenes, ecuaciones y enlaces a sitios web o a funciones de MATLAB^®. Puede modificar el tipo y el aspecto de la anotación; por ejemplo, puede agregar ecuaciones matemáticas en LaTeX o MathML.

Puede agregar líneas de conexión entre una anotación y un bloque colocando el cursor sobre el contorno de la anotación y arrastrando la línea de conexión hasta el bloque deseado. Puede delimitar áreas del modelo para agrupar bloques relacionados visualmente y mejorar la legibilidad del modelo, ya sea con la paleta o arrastrando un recuadro alrededor del área de interés y seleccionando Create Area en la barra de acciones. Las áreas se pueden etiquetar para indicar la relación entre los bloques.

La Figura 3 ilustra estas técnicas de anotación.

Documentación de bloques y señales

A medida que avance el diseño, probablemente trabajará con cientos o incluso miles de bloques y señales, lo que hará que el modelo resulte aún más difícil de leer.

Puede mejorar la claridad del diseño de inmediato asignando nombres a señales y bloques (Figura 4). Para introducir o editar el nombre de una señal, haga clic con el botón secundario en la señal y seleccione Properties, o haga doble clic en la señal. Para asignar un nombre a un bloque, haga clic en el nombre predeterminado que aparece justo debajo del bloque.

Más información sobre control del formato, estilo y aspecto de un bloque.

Introduzca descripciones para un bloque o una señal en el campo correspondiente de las propiedades del bloque o de la señal. Después, puede mostrar la descripción y otras propiedades del bloque debajo del icono del bloque o cuando se coloca el cursor sobre el bloque. En la Figura 4 se muestran bloques y señales con anotaciones. También puede incluir la descripción del bloque como comentario en el código C/C++ generado a partir del modelo.

Si utiliza máscaras para definir interfaces personalizadas en los bloques, igualmente puede proporcionar una descripción en el panel Documentation de Mask Editor (Figura 5). El campo Help del mismo panel permite introducir la información que desee mostrar cuando el usuario del bloque enmascarado haga clic en el botón Help del cuadro de diálogo de la máscara.

Incorporación de notas en capas del modelo

A medida que los modelos crecen, se agregan más capas a la jerarquía, lo que dificulta obtener una visión completa. Puede anotar capas individuales de un modelo con marcadores de vista, notas y el bloque DocBlock.

Los marcadores de vista marcan partes de un modelo. Puede utilizarlos para ir directamente a partes específicas del modelo y proporcionar detalles o comentarios sobre vistas específicas. Para crear un marcador de vista, seleccione el botón Viewmark This View de la paleta en la parte del modelo que desee capturar. Haga clic en el botón Viewmarks para ver los marcadores de vista y agregar descripciones o comentarios (Figura 6).

Para agregar notas a las capas de la jerarquía del modelo, primero cree un archivo de notas. Las notas pueden incluir imágenes y enlaces, así como URL (Figura 7). Si el modelo ya tiene notas asociadas, el panel Notes muestra el contenido de la capa actual a medida que se recorre la jerarquía. 

El bloque DocBlock ofrece otra forma de agregar notas. Si hace doble clic en una instancia del bloque, se crea un archivo temporal con el texto asociado a este bloque y el archivo se abre en un editor (Figura 8). Tenga en cuenta que puede utilizar el texto de comentario de un bloque DocBlock como comentario global que aparece en el código generado a partir del modelo.

Documentación de objetos de bus, de señal y de parámetro

Un modelo de Simulink suele depender de variables y datos almacenados fuera del modelo. Por ejemplo, los objetos de bus, de señal y de parámetro se suelen almacenar en el área de trabajo base. Puede describir el propósito y el funcionamiento de un objeto con la propiedad Description. Esto se puede hacer mediante programación:

>> myParam = Simulink.Parameter; myParam.Description = 'This is the parameter description';

o desde el cuadro de diálogo correspondiente, al que se accede desde Model Explorer o haciendo doble clic en el objeto (Figura 9).

Si utiliza Embedded Coder^® para generar código a partir del modelo, puede agregar las descripciones de los objetos de bus, de señal y de parámetro como comentarios de las declaraciones de variables en el código generado (Figura 10).

Más información sobre inserción de descripciones de objetos de datos de Simulink como comentarios en el código generado y adición de comentarios personalizados al código generado.

Siguientes pasos

Si un proyecto incluye múltiples modelos de Simulink, existen formas de ampliar estas técnicas a todo el proyecto. Productos como Simulink Report Generator™ y Requirements Toolbox™, y Projects amplían de forma natural las técnicas descritas en este artículo.

Con Simulink Report Generator, puede diseñar informes de los modelos y generarlos automáticamente en formatos comunes, como PDF, Microsoft^® Word^®, Microsoft PowerPoint^® y HTML.

Requirements Toolbox permite crear requisitos de texto enriquecido y enlazarlos con diseños, código y pruebas. Puede comprobar el estado de implementación y verificación de los requisitos, lo que permite evaluar el grado de finalización del proyecto.

Projects permite organizar proyectos y promover tanto un trabajo en equipo eficiente como la productividad individual. Puede gestionar todos los archivos del proyecto en un solo lugar, ver y etiquetar archivos para flujos de trabajo de revisión por homólogos, y realizar el seguimiento de los proyectos y compartirlos con herramientas externas de control de versiones, como Subversion^® o Git™.