Generación Automática de Documentación

GENERACIÓN AUTOMÁTICA DE
DOCUMENTACIÓN A TRAVÉS DE
UN ARCHIVO XML

Mikel Belausteguigoitia
Oihane Crucelaegui
Maialen Magalhaes
Imanol Vellón

Página 0
 Generación Automática de Documentación

Índice

Índice
1 Introducción ....................................................................................................... 2

2 Objetivo ............................................................................................................. 4

3 Lenguaje de Modelado UML ............................................................................. 5

4 Metodología de Trabajo ..................................................................................... 7

5 Formato de la Documentación ........................................................................... 8

5.1 Lista de Componentes Hardware................................................................ 8

5.2 Lista de la Arquitectura Hardware de los Nodos ........................................ 8

5.2.1 Nodo Procesador ........................................................................................ 8

5.2.2 Nodos Entrada/Salida ............................................................................... 10

5.2.3 Segmentos de Bus ..................................................................................... 12

6 Implementación ............................................................................................... 14

7 Resultados Obtenidos ...................................................................................... 18

8 Conclusiones .................................................................................................... 19

Página 1
 Generación Automática de Documentación

Grupo 2

1 Introducción
En el proceso de diseño de sistemas de control industrial no solo se deben tener en
cuenta las especificaciones funcionales, qué hace el sistema, sino también las no funcionales,
cómo lo hace y qué restricciones existen.

Cuando se diseña un sistema de control una de las mayores dificultades es

precisamente definir correctamente las especificaciones en todos los niveles, conocer las
restricciones y gestionar la relación entre ellas. Como solución a este problema, cuya
complejidad se deriva principalmente del tamaño del sistema, surge la idea de realizar el
diseño basado en modelos.

Lo que se hace es definir distintos puntos de vista, llamados dominios: dominio

funcional, dominio de la arquitectura software y dominio de la arquitectura hardware. Una vez
definidos los dominios se realiza un modelo1 del sistema para cada dominio, para lo cual se
define un lenguaje o metamodelo2 especifico de cada dominio.

El modelo completo del sistema está compuesto por el modelo de cada dominio más
las relaciones entre los dominios.

En este proyecto se ha realizado el modelado de un sistema de control a través de los

modelos funcional, hardware y software.

El diseño basado en modelos además de ayudar en la gestión de la complejidad en el

diseño de un sistema conlleva otras ventajas entre las que destacan la trazabilidad de los
requisitos y la generación de código.

1
Modelo: representación parcial o simplificada de la realidad que recoge aquellos aspectos de relevancia
para las intenciones del modelador, y de la que se pretende extraer conclusiones de tipo predictivo. Se
modela para comprender mejor o explicar mejor un proceso o unas observaciones. Un mismo objeto
puede ser modelado con distintas técnicas y distintas intenciones, de forma que cada modelo resalta sólo
ciertos aspectos del objeto.
2
Metamodelado: es el análisis, construcción y desarrollo de los marcos, las reglas, las limitaciones, los
modelos y teorías aplicables y útiles para el modelado de una clase predefinida de los problemas.

Página 2
 Generación Automática de Documentación

Grupo 2

El objetivo de este proyecto es la generación automática de documentación a partir de

un modelo. Esto es posible porque un modelo realizado en UML puede ser exportado a un
fichero de texto en XML y se ha definido el estándar XMI (XML Metada Interchange) que
especifica la forma en la que es posible intercambiar modelos UML entre distintas
herramientas de modelado. En definitiva, el objetivo es extraer la información referente al
modelo contenido en el XMI y generar la documentación requerida.

Página 3
 Generación Automática de Documentación

Grupo 2

2 Objetivo
El objetivo del presente proyecto es generar de forma automática la documentación de
la Estación 1- Ubicación Base. Concretamente, se trata de generar la siguiente
documentación:

• La lista general de componentes hardware por la que está compuesta la

estación.
• La lista de la arquitectura hardware de los nodos, distinguiendo entre:

Nodo Procesador.

Nodos Entrada/Salida.

Segmentos de bus.

Para la consecución de dicho objetivo, vamos a partir del modelo de la Estación 1, que
se ha realizado con el lenguaje de modelado UML.

Página 4
 Generación Automática de Documentación

Grupo 2

3 Lenguaje de Modelado UML

Tal y como se ha comentado en el punto 2, objetivo del proyecto, tenemos que partir
del modelo de la Estación 1. Para ello, vamos a utilizar el lenguaje de modelado UML.

El Lenguaje Unificado de Modelado (UML) es un lenguaje gráfico para visualizar,

especificar, construir y documentar un sistema. Es decir, es un lenguaje de modelado que
permite la representación conceptual y física de un sistema.

Hay que resaltar que UML es un "lenguaje de modelado" para especificar o para
describir métodos o procesos. Se utiliza para definir un sistema, para detallar los artefactos en
el sistema y para documentar y construir. En otras palabras, es el lenguaje en el que está
descrito el modelo.

UML cuenta con varios tipos de diagramas, los cuales muestran diferentes aspectos de
las entidades representadas. En nuestro caso, los más importantes son los siguientes.

• Diagrama de clases: es un tipo de diagrama estático que describe la estructura del

sistema mostrando sus clases, atributos y las relaciones entre ellos. Se utilizan durante
el proceso de diseño, donde se crea el diseño conceptual de la información que se
manejará en el sistema, y los componentes que se encargaran del funcionamiento y la
relación entre uno y otro.
• Diagrama de componentes: representa cómo un sistema de software es dividido en
componentes y muestra las dependencias entre estos componentes. Pueden ser usados
para modelar y documentar cualquier arquitectura de sistema.
• Diagramas de objetos: se puede considerar un caso especial de un diagrama de clases
en el que se muestran instancias específicas de clases (objetos) en un momento
particular del sistema. Los diagramas de objetos utilizan un subconjunto de los
elementos de un diagrama de clase. Los diagramas de objetos no muestran la
multiplicidad ni los roles, aunque su notación es similar a los diagramas de clase.
• Diagrama de Despliegue: es un tipo de diagrama que se utiliza para modelar el
hardware utilizado en las implementaciones de sistemas y las relaciones entre sus
componentes. Los elementos usados por este tipo de diagrama son nodos,
componentes y asociaciones.

Página 5
 Generación Automática de Documentación

Grupo 2

Es indudable que el modelo de la estación va a contener particularidades que ningún

lenguaje, va a poder describirlas todos a la vez. Es por esto que parte de la especificación del
UML se dedica a definir mecanismos de extensión con miras a incrementar el campo de
aplicación del lenguaje. El mecanismo de extensión, que hemos utilizado nosotros, es el
llamado estereotipo; Un estereotipo representa una distinción de uso. Se trata de pequeñas
etiquetas que aplicadas a los elementos o relaciones de un diagrama indican significado
adicional.

Una vez que tenemos el modelo completo estereotipado de la Estación 1, generamos el

archivo XML que es el documento de base sobre el que realizaremos la búsqueda de
información. Notar que es posible ampliar el modelo de la estación, pero gracias a la ventaja
de que XML es extensible, solo hay que extenderlo con la adicción de nuevas etiquetas, de
modo que se puede continuar utilizando sin mayor complicación.

A continuación se muestra un ejemplo para ver la estructura del documento XML

generado:
<nestedNode xmi:type="uml:Device" xmi:id="Ue9cfb082-bc42-4930-b20d-
a41fe088a3de" xmi:uuid="e9cfb082-bc42-4930-b20d-a41fe088a3de"
name="S1_PowerSupply">
<xmi:Extension extender="UModel">
<appliedStereotype xmi:type="uml:StereotypeApplication"
xmi:id="U04213ff2-6f9b-40ad-8f3a-ae2bbffa7bc8" xmi:uuid="04213ff2-6f9b-
40ad-8f3a-ae2bbffa7bc8" visibility="unspecified" classifier="U44640d98-
4882-42fd-8bf5-47ab398ee58d">
<slot xmi:type="uml:Slot" xmi:id="U3c8c722f-6f28-4c54-a0ee-
ab65a5c9ecca" xmi:uuid="3c8c722f-6f28-4c54-a0ee-ab65a5c9ecca"
definingFeature="U00c24948-68a6-4ba2-9f1c-17628f21de84">
<value xmi:type="uml:LiteralString" xmi:id="U7a4620ea-a7fc-4f5c-b13b-
ad93a052d2bf" xmi:uuid="7a4620ea-a7fc-4f5c-b13b-ad93a052d2bf"
value="S1_PowerSupply"/>

El motivo de usar la tecnología XML es porque expresa la información de forma

estructurada, esto es, la información se compone de partes bien definidas, y esas partes se
componen a su vez de otras partes. . Entonces se tiene un árbol de trozos de información.
Estas partes se denominan elementos, y se las señala mediante etiquetas. Los elementos XML
pueden tener contenido, o bien ser elementos vacíos. A su vez, los elementos pueden tener
atributos, que son una manera de incorporar características o propiedades a dichos elementos.
Por otra parte, los documentos XML sólo permiten un elemento raíz del que todos los demás
sean parte, es decir, solo pueden tener un elemento inicial.

En base a esta estructura, construiremos un algoritmo iterativo que recorra el

documento XML para encontrar la información que nos interesa y mostrarla por pantalla.

Página 6
 Generación Automática de Documentación

Grupo 2

4 Metodología de Trabajo
El proceso de trabajo que seguimos, consta de las siguientes etapas:

- Modelado de la Estación 1.
- Generación de código XML a partir del modelo creado.
- Construcción de un algoritmo iterativo que nos proporcione la información que
requerimos para generar la documentación.
- Por último, generación de un archivo para presentar la información filtrada.

Página 7
 Generación Automática de Documentación

Grupo 2

5 Formato de la Documentación
A continuación se muestra el formato que queremos generar para documentar la
información. El objetivo es resumir toda la información disponible en una tabla que refleje y
resuma dicha información, para que en un solo vistazo nos hagamos una idea de la
composición Hardware de la Estación 1.

5.1 Lista de Componentes Hardware

Esta lista refleja todos los dispositivos que contiene el modelo de la estación, los
cuales se resumen a continuación:

Unit Description Serial Number

3 Fuente de Alimentación S1_PS

1 Procesador S1_P

5 Digital Input S1_DI

5 Digital Output S1_DO

3 Enlace Ethernet S1_ETHERNET

5.2 Lista de la Arquitectura Hardware de los Nodos

El objetivo de esta lista es obtener las características principales tales como nombre,
número de serie, posición y descripción de todos los dispositivos que componen cada nodo. A
su vez, también vamos a obtener una tabla resumen que nos va a indicar los nodos que une el
segmento de bus.

5.2.1 Nodo Procesador

El Autómata programable de la estación 1 (S1_PLC) es nuestro Nodo Procesador,

que va estar compuesto por los siguientes dispositivos (ver figura nº1):

- Un procesador
- Una fuente de alimentación
- Cuatro tarjetas de Entradas/Salidas
- Una tarjeta Ethernet

Página 8
 Generación Automática de Documentación

Grupo 2

Figura Nº1. Nodo Procesador (S1_PLC) de la estación 1- Ubicación Base.

La documentación que habría que generar, tendría el siguiente aspecto:

Name Serial Number Position Description

Fuente de
Power Supply S1_PowerSupply S1_PS 1
Alimentación

Proccesor S1_P 2222 2 Procesador

S1_DI_1 S1_DI 3 Digital Input

S1_DI_2 S1_DI 4 Digital Input

IO Board
S1_DO_1 S1_DO 5 Digital Output

S1_DO_2 S1_DO 6 Digital Output

Communication
S1_ETHERNET S1_ETHERNET 7 Enlace Ethernet
Board

Página 9
 Generación Automática de Documentación

Grupo 2

5.2.2 Nodos Entrada/Salida

Se trata de los nodos que hemos denominado Esclavo_profibus_1 y

Esclavo_profibus_2. La característica que hace que se diferencien del nodo procesador, es
que no disponen del dispositivo procesador. A continuación, se enumeran los dispositivos que
los componen:

- Una fuente de alimentación

- Una tarjeta Ethernet
- Cuatro tarjetas de Entradas/Salidas para el Esclavo_Profibus_1 (ver figura nº3)
- Dos tarjetas de Entradas/Salidas para el Esclavo_Profibus_2 (ver figura nº4)

Figura Nº2. Nodo Esclavo_Profibus_1 de la estación 1- Ubicación Base.

Página
10
 Generación Automática de Documentación

Grupo 2

Figura Nº3. Nodo Esclavo_Profibus_2 de la estación 1- Ubicación Base.

La tabla resumen que contiene la información de dichos nodos, se presenta a

continuación:

• Esclavo_Profibus_1

Name Serial Number Position Description

Fuente de
Power Supply S1_PowerSupply S1_PS 1
Alimentación

S1_DI_1 S1_DI 3 Digital Input

S1_DI_2 S1_DI 4 Digital Input

IO Board
S1_DO_1 S1_DO 5 Digital Output

S1_DO_2 S1_DO 6 Digital Output

Communication
S1_ETHERNET S1_ETHERNET 7 Enlace Ethernet
Board

Página
11
 Generación Automática de Documentación

Grupo 2

• Esclavo_Profibus_2

Name Serial Number Position Description

Fuente de
Power Supply S1_PowerSupply S1_PS 1
Alimentación

S1_DI_1 S1_DI 3 Digital Input

IO Board
S1_DO_1 S1_DO 5 Digital Output

Communication
S1_ETHERNET S1_ETHERNET 7 Enlace Ethernet
Board

5.2.3 Segmentos de Bus

Es el elemento que realiza la conexión entre los nodos que hemos generado. Para
obtener información de este elemento y poder generar la documentación, partimos de las
asociaciones que hemos creado para unir dichos nodos (ver figura nº4).

Figura Nº4. Bus Profibus_DP1.

Página
12
 Generación Automática de Documentación

Grupo 2

La información resumida queda de la siguiente manera:

Node Serial Number

S1_PLC Processing Node

Esclavo_Profibus_1 IO Node

Esclavo_Profibus_2 IO Node

Página
13
 Generación Automática de Documentación

Grupo 2

6 Implementación
A continuación, se explica el algoritmo implementado para obtener la tabla de los
componentes Hardware. Para generar el resto de documentación se reutilizara la mayor parte
del código, indicando puntualmente las diferencias encontradas.

El primer paso, consiste en decirle al programa donde se encuentra el fichero .xmi,

para ello utilizamos la instrucción Load y le indicamos el path donde se encuentra el fichero.
A continuación, nos situamos en el elemento raíz del documento .xmi (NodoRaíz) y
generamos MiLista, que contiene los nestedNode.

MiXml->Load("..\\docxmi\\Celula 1_v1.xmi");
XmlElement^ NodoRaiz = MiXml->DocumentElement
XmlNodeList^ MiLista = NodoRaiz->GetElementsByTagName("nestedNode");

El siguiente paso, es hallar los identificadores serialNumber y description, que genera

el .xmi que por defecto se asocia al perfil que hemos aplicado en el modelo de la Estación.
Para lograr dicho objetivo se crea MiLista2, que contiene los ownedAttribute y MiLista3, que
contiene los packagedElement y se recorren ambas listas para guardar en SerialId y el
descrptionId.

//Para hallar el identificador del SerialNumber

XmlNodeList^ MiLista2 = NodoRaiz->GetElementsByTagName("ownedAttribute");
for(int i = 0; i<MiLista2->Count; i++)
{if(((XmlElement^)MiLista2[i])->GetAttribute("name")->Equals("serialNumber"))
{SerialId = ((XmlElement^)MiLista2[i])->GetAttribute("xmi:id");}
}
//Para hallar el identificador de Description
XmlNodeList^ MiLista3 = NodoRaiz->GetElementsByTagName("packagedElement");
for(int i = 0; i<MiLista3->Count; i++)
{if(((XmlElement^)MiLista3[i])->GetAttribute("name")-
>Equals("GenericComponent"))
{lista_gc->Add(MiLista3[i]);
XmlNodeList^ lista_gc1 = lista_gc[0]->ChildNodes;
for(int j = 0; j<lista_gc1->Count; j++)
{if(((XmlElement^)lista_gc1[j])->GetAttribute("name")-
>Equals("description"))
{descriptionId = ((XmlElement^)lista_gc1[j])-
>GetAttribute("xmi:id");}}}}

Página
14
 Generación Automática de Documentación

Grupo 2

A continuación, se genera una lista de dispositivos, lista_device, a partir de MiLista

que contiene todos los dispositivos que cuelgan de los nodos.

for(int i = 0; i<MiLista->Count; i++)

{
if(((XmlElement^)MiLista[i])->GetAttribute("xmi:type")-
>Equals("uml:Device"))
{
lista_device->Add(MiLista[i]);
Prueba = ((XmlElement^)lista_device[0])-
>GetAttribute("name");}}

En las siguientes líneas, se muestra la creación de la lista_slot, que contiene los

atributos de los dispositivos. Se identifican los slots del serialNumber y description y se
guardan dichos valores en serial_value y en description. También se comprueban aquellos
dispositivos que tienen el mismo serialNumber, para realizar su suma.

for (int j=0; j<lista_device->Count; j++)

{
XmlNodeList^ lista_slot = lista_device[j]->ChildNodes[0]-
>ChildNodes[0]->ChildNodes;
for(int i=0; i<lista_slot->Count; i++)
{
if(((XmlElement^)lista_slot[i])-
>GetAttribute("definingFeature")==SerialId)
{for(int k=0; k<a; k++) {
if(serial_value[k]==((XmlElement^)((XmlElement^)lista_slot[i])-
>ChildNodes[0])->GetAttribute("value"))
{ contador[k]++;
salto=1;}}
if (salto==0){
serial_value[a] =
((XmlElement^)((XmlElement^)lista_slot[i])->ChildNodes[0])-
>GetAttribute("value");
for(int l=0; l<lista_slot->Count; l++)
{if(((XmlElement^)lista_slot[l])-
>GetAttribute("definingFeature")==descriptionId)
{description[a] =
((XmlElement^)((XmlElement^)lista_slot[l])->ChildNodes[0])-
>GetAttribute("value");
}}
contador[a]++;
a++;}
else
salto=0;}}}

Página
15
 Generación Automática de Documentación

Grupo 2

Por último, se muestra por pantalla, los resultados obtenidos.

if (myfile.is_open())
{
myfile<<"<table border=1>\n";
myfile<<"<tr><th>Unit</th>";
myfile<<"<th>Description</th>";
myfile<<"<th>Serial Number</th></tr>\n";
for(int fil = 0; fil<devices_max; fil++)
{
myfile<<"<tr><td align=center>";
myfile<<devDoc[fil].contador;
myfile<<"</td><td align=center>";
myfile<<devDoc[fil].Description;
myfile<<"</td><td align=center>";
myfile<<devDoc[fil].Serial_ID;
myfile<<"</td></tr>\n";
}
myfile<<"</table>";
myfile.close();
}

Para obtener la tabla de la arquitectura Hardware de los Nodos, la primera apreciación

que hay que tener en cuenta, es la de poder diferenciar entre Nodo Procesador y Nodo
Entrada/Salida. Debido a la imposibilidad de realizar esta distinción y con objeto de poder
generar la documentación de acuerdo a los requisitos demandados, optamos por declarar el
atributo serialNumber del estereotipo aplicado Nodo (ver figura nº 4). De esta manera,
tenemos nuestro punto de partida para distinguir ambos nodos.

for(int i = 0; i<lista_nodos->Count; i++)

{
for(int j = 0; j<lista_nodos[i]->ChildNodes->Count; j++)
{if(lista_nodos[i]->ChildNodes[j]->HasChildNodes)
{AppliedStereotypeSlots = ((XmlElement^)lista_nodos[i]-
>ChildNodes[j]->ChildNodes[0])->GetElementsByTagName("slot");
for(int k = 0; k<AppliedStereotypeSlots->Count;
k++)
{if(((XmlElement^)AppliedStereotypeSlots[k])-
>GetAttribute("definingFeature")->Equals(SerialId))

{if(((XmlElement^)((XmlElement^)AppliedStereotypeSlots[k])-
>ChildNodes[0])->GetAttribute("value")->Equals("Processing Node"))
{lista_nodos_procesador-
>Add(lista_nodos[i]);
}
if(((XmlElement^)((XmlElement^)AppliedStereotypeSlots[k])-
>ChildNodes[0])->GetAttribute("value")->Equals("IO Node"))
{lista_nodos_IO->Add(lista_nodos[i]);
}}}}}}

Página
16
 Generación Automática de Documentación

Grupo 2

Con el propósito de identificar a que nodo corresponde cada dispositivo, se añaden los
dispositivos como elementos nuevos creados directamente a partir del nodo en cuestión (ver
figura nº 5).

Figura Nº5. Ventana Model Tree del programa Altova U-Model

En este caso, necesitamos hallar la lista de los identificadores (classifier) Processor,

PowerSupply, IOBoard y CommunicationBoard. Dichos identificadores se almacenaran en las
variables ProccesorClassifier, PowSupplyClassifier, IOBoardClassifier y
ComBoardClassifier respectivamente, que utilizaremos para conocer qué tipo de dispositivo
cuelga de cada nodo.

for(int i = 0; i<lista_classifiers->Count; i++)

{if(((XmlElement^)lista_classifiers[i])->GetAttribute("name")-
>Equals("Processor"))
{ProcessorClassifier = ((XmlElement^)lista_classifiers[i])-
>GetAttribute("xmi:id");}
if(((XmlElement^)lista_classifiers[i])->GetAttribute("name")-
>Equals("PowerSupply"))
{PowSupplyClassifier = ((XmlElement^)lista_classifiers[i])-
>GetAttribute("xmi:id");}
if(((XmlElement^)lista_classifiers[i])->GetAttribute("name")-
>Equals("IOBoard"))
{IOBoardClassifier = ((XmlElement^)lista_classifiers[i])-
>GetAttribute("xmi:id");}
if(((XmlElement^)lista_classifiers[i])->GetAttribute("name")-
>Equals("CommunicationBoard"))
{ComBoardClassifier = ((XmlElement^)lista_classifiers[i])-
>GetAttribute("xmi:id");}}

Una vez conocido el tipo de dispositivo que es, se obtienen los valores de los atributos
que tiene definido. Y por último, al igual que el caso anterior, se muestra por pantalla la tabla
generada.

//El codigo es similar al caso de la lista de los dispositivos

Página
17
 Generación Automática de Documentación

Grupo 2

7 Resultados Obtenidos
Las siguientes imágenes, muestran el contenido de la documentación generada.

Figura Nº6. Tabla de Componentes Hardware.

Figura Nº7. Tabla de Arquitectura Hardware de los Nodos.

Página
18
 Generación Automática de Documentación

Grupo 2

8 Conclusiones
El algoritmo que hemos generado nos permitiría obtener de forma automática la
documentación de cualquier estación que se modele, siempre y cuando se apliquen los
mismos perfiles que se han utilizado a la hora de modelar esta estación. Por lo tanto, la mayor
ventaja que nos proporciona este código es la posibilidad de reutilización que nos brinda.
Esto se debe gracias al lenguaje de esquema que utiliza XML, donde la estructura y las
restricciones de los contenidos de los documentos se describen de una forma muy precisa.

Otra característica importante es que se trata de un código robusto y confiable,

entendiendo como tal, aquel código donde se minimizan los errores de compilación.

Página
19