LA DOCUMENTACION AUTOMATIZADA

Documentación automatizada

En muchas ocasiones se pide un manual de referencia del código. Esto es especialmente importante a la hora de crear una librería que esté ideada para que otro programador la use en una aplicación final. Este manual engloba de alguna forma un trabajo doble: hay que explicar bien el funcionamiento de cada función en el código mismo y luego repetir la misma información en un documento de texto.

De este trabajo pueden encargarse sistemas de documentación automáticos. Leen el código y extraen la información necesaria para generar la documentación. Muchas veces permiten varios tipos de documentos de salida: en formato HTML, en formato PDF, como fichero de HTML comprimida (CHM) o en formato “Rich Text”.

Probablemente el más influyente de estos sistemas es javadoc. Fue incluido en el entorno Java de Sun como una parte integral del sistema y ha marcado desde entonces el formato de los comentarios de documentación. El programa de más uso es probablemente doxygen, ya que puede entender la sintaxis de muchos lenguajes, muy especialmente de C++. Para PHP es recomendable usar phpDocumentor.

A todos estos sistemas es común que requieren un marcador especial para los comentarios que se exportan del código a la documentación final. El más extendido es el de javadoc que marca los comentarios entre /** y */. Nota que es nada más que un comentario al estilo /* … */ donde la primera letra es un asterisco. Sin embargo, para el sistema de documentación, el segundo asterisco en /** lo marca como un comentario de documentación cuyo contenido será procesado por el sistema de documentación automatizado.

Dentro de este bloque están permitido una multitud de etiquetas (tags en inglés) que dependen del objeto documentado, por ejemplo si es un fichero una clase o una función. La declaración de una función podría parecerse a algo como esto:

* La primera frase es un título/resumen de la función. Después del

* punto que delimita la primera frase comienza la documentación

* detallada. Características especiales están marcadas con una

* etiqueta.

* @param parametro El parámetro de la función.

* @return La función devuelve un resultado.

int mi_funcion(int parametro);

Guarda tus ficheros fuentes en Unicode si quieres tener acentos correctos en la documentación. Esto vale al menos para phpDocumentor.

Los sistemas de documentación sólo documentan declaraciones, objetos y tipos globales, ficheros y inclusiones. No documentan el cuerpo de una función ya que se supone que no es algo importante en un manual de referencia. Sin embargo ofrecen una etiqueta @internal con información interna, que sólo se compila con un cierto flag activado. De la misma forma se puede documentar o no variables y métodos privados.

Es cierto que los sistemas de documentación requieren algún esfuerzo al principio para instalar y entenderlos. Sin embargo, una vez superado esta fase ofrecen tener una documentación actualizada prácticamente en tiempo real que con sus enlaces y agrupaciones son una ayuda incluso para el autor durante el desarrollo.

FUENTES DE INFORMACION DOCUMENTAL

as fuentes documentales son datos o estudios realizados previamente sobre los temas que uno desea investigar, los cuales ya existen en algún medio como informes, paginas web, libros, investigaciones previas, documentos, etc. En la investigación documental la recolección de datos se efectúa por medio de fichas. Si es una información secundaria interna es porque ha sido creada en el pasado por el mismo investigador, y si es externa es porque fue generada por terceros externos a él.

Este tipo de fuente es muy útil porque evita hacer investigaciones donde otros ya lo han hecho, para ganar tiempo, esfuerzo y ahorrarse en costos. Además un solo investigador puede no estar capacitado para recoger de primera mano toda la información que necesita.

Las fuentes documentales o fuentes secundarias de datos se dividen en:

Fuentes documentales de primera mano: Son los documentos originales que contienen información fidedigna y que no ha sido alterada o distorsionada para fines específicos. Ej. Códices, informes científicos, disertaciones doctorales de universidades, etc.

Fuentes documentales de segunda y tercera mano: documentos o material impreso que contienen datos de fuentes originales, pero que han sido distorsionados o modificados, un ejemplo de documentos de segunda mano son textos didácticos, diarios, periódicos, informes gubernamentales, libros de divulgación popular. Ejemplo de documentos de tercera manos son libros de texto, revistas no científicas, algunas monografías, etc.

BIBLIOTECAS VIRTUALES.

Una biblioteca digital o virtual es un centro de recursos informáticos documentales, al que se accede por medio del uso de dispositivos de comunicación móvil a través de los servicios de internet. En el concepto de biblioteca digital está implícita la integración de la técnica informática y las comunicaciones basadas en la función del internet. La información ofrecida suele estar disponible en formatos pdf, doc, jpg, bmp o mp3, entre otros.

Índice [ocultar]

1 Características

2 Historia

3 Bibliotecas digitales

4 Véase también

5 Enlaces externos

Características[editar • editar código]

Para hablar de una biblioteca digital es necesario que las fuentes de información estén a disposición del usuario y su acceso tenga ubicuidad, sin importar dónde residan físicamente; ni quién se encargó específicamente de su procesamiento y almacenamiento. Algunos de los recursos que conforman una biblioteca digital pueden ser : enciclopedias, libros, revistas, periódicos, materiales didácticos, cursos de superación personal, entre muchos más.

Predomina el concepto de biblioteca como espacio y como proceso, lo cual manifiesta el dinamismo que le impulsa el internet. Lo digital tiene que ver con el propósito y la flexibilidad del sistema de medios de la biblioteca para lograr articularse con flexibilidad y responder a diversas demandas de los usuarios. Lo digital -en este contexto- se relaciona con el hecho que la biblioteca es relativa en espacio y tiempo, porque sus límites funcionales no los marca la geografía y su disponibilidad temporal es instancia de la demanda de quien la consulta.

Una biblioteca digital debe permitir que los documentos estén disponibles cuando

...