Documentation generator for VHDL and Matlab source codes for photonic and electronic systems B. Niton, K.T. Pozniak, R.S. Romaniuk Institute of Electronic Systems, Warsaw University of Technology, Nowowiejska 15/19 Warsaw, Poland ABSTRACT The UML, which is a complex system modeling and description technology, has recently been expanding its uses in the field of formalization and algorithmic approach to such systems like multiprocessor photonic, optoelectronic and advanced electronics carriers; distributed, multichannel measurement systems; optical networks, industrial electronics, novel R&D solutions. The paper describes a new concept of software dedicated for documenting the source codes written in VHDL and MatLab. The work starts with the analysis of available documentation generators for both programming languages, with an emphasis on the open source solutions. There are presented own solutions which base on the Doxygen program available as a free license with the source code. The supporting tools for parsers building were used like Bison and Flex. The documentation generator application is used for design of large optoelectronic and electronic measurement and control systems. The paper consists of three parts which describe the following components of the documentation generator for photonic and electronic systems: concept, MatLab application and VHDL application. This is part one which describes the system concept. Part two describes the MatLab application. MatLab is used for description of the measured phenomena. Part three describes the VHDL application. VHDL is used for behavioral description of the optoelectronic system. All the proposed approach and application documents big, complex software configurations for large systems. Keywords: optical networks, large electronic and optoelectronic systems, documentation, source codes, VHDL, Matlab, Doxygen, UML, MatLab algorithms for large functional systems, VHDL description of complex systems, photonics applications, software for photonics and electronics systems 1. INTRODUCTION Documenting of the complex source codes for large systems is usually a tiresome and work consuming process. It was soon decided to try to automatize this process, at least in the critical parts. A number of tools was prepared. These are called documentation generators for source codes. Large optoelectronic and electronic systems, including optical networks, are now managed by complex codes including MatLab, C++, VHDL and others. A proper documentation is a must. Properly documented code is simpler for further application, where the functions, classes, or other language structures are described. The software engineer may faster determine their tasks in the program. Additionally, proper documentation of the source codes helps in the realization of larger projects, on which are working larger groups of programmers. It is much simpler to combine two software modules written by two different persons, when there is an access to their full documentation. A properly written code fosters the discovery of errors in the project and facilitates the usage (re-usage) of its fragments in other applications under development. Proper documenting of program source codes brings only the advantages. It is, however, frequently one of the last stages in the project realization, for which there is nearly no time. Documentation is sometimes omitted due to lack of time, lack of resources, or small emphasis put on this subject. Preparation of a separate document describing the implementation, and done in parallel with writing of the source code is tiresome and quite awkward. Documentation generators seem to be efficient and irreplaceable. They describe programs in a standardized and succinct, yet satisfactory, way. They use for description the comments left directly in the source code. They also use for description the alone structure of the code. The information in the source code is easy to be updated. It is enough to Optical Fibers and Their Applications 2011, edited by Jan Dorosz, Ryszard S. Romaniuk, Proc. of SPIE Vol. 8010, 80100R · © 2011 SPIE · CCC code: 0277-786X/11/$18 · doi: 10.1117/12.898392 Proc. of SPIE Vol. 8010 80100R-1 Downloaded from SPIE Digital Library on 25 Jun 2011 to 194.29.135.8. Terms of Use: http://spiedl.org/terms change the comments while rewriting the source code. Usage of the description generator instead is useful for the software engineer, as the information contained in the code is transformed automatically to the user friendly format. The documentation generators may be divided according to the output format they give. Some documentation generators are available via the web and give the output in the HTML format. Some of them generate printable forms like ps, pdf or rtf. Some of them describe only the code structure and give the output in the XML format. The documentation generators, for the source codes, usually give more than a single output format. They may generate several formats, depending on the user’s choice. The most popular output form, sometimes the only one, without any other choice is the HTML [2-40, 45-46]. Multiple output forms are available from the following generators: Ddoc, ROBODoc, fpdoc and Doxygen [9, 15, 33, 45]. Now, the available description generators are complex systems which may do the documentation for numerable programming languages, with this ability sometimes simultaneously embedded in a single product [2-40, 45-46]. Only few documentation generators provide cooperation with the hardware description languages, as for example the VHDL. The majority of documentation generators is dedicated for high level languages, omitting however the MatLab. Own research on the automatic generation of the documentation of source codes written in the VHDL shown that there is a serious, and not yet filled, niche in this area. One of the exceptions in this are is the Doxygen, an advanced program offering a wide choice of the output formats and the supported programming languages (input formats) [45]. The second versatile program is VHDLDOC written by CERN [39], and targeting the local needs to build large photonic and electronic systems not only but predominantly for high energy physics experiments. The system is, of course, easily adaptable for industrial conditions. The biggest advantage of these two programs is that they are free and available on GPL license. This means open access to their source codes. Representatives of commercial programs generating documentation for the VHDL are: TwinText and UniversalReport [34, 35]. The most universal tools in the debated area are offered by advanced programs generating documentation for arbitrary language, supplemented with any sort of comments. This group or programs includes: ROBODoc and NaturalDocs [27, 33]. The most frequently used programs in the academic environment are Doxygen and VHDLDOC. Only few programs generate documentation for MatLab. One of such applications is M2HTML [40], which is written in the MatLab code. The documentation is generated in the HTML format. An essential drawback of this program is that it does not support for documentation of classes and inheriting mechanisms from the MatLab language. The alternative solutions are in the commercial programs like Doc-o-Matic and UniversalReport, as well as the documentation mechanism embedded in the MatLab [11. 35]. The comments are added to the m-files. The comments may be browsed using the MatLab help request with the following arguments: file name, function, class, even the whole folder name [41]. There is no possibility, however, in the MatLab to combine all the comments (and other auxiliary data on the source code) into a single homogeneous help structure, linked for example by means of hyperlinks. Summing up this digest of available resources in the area of documentation generation, there is no a single application available, which is free, complete, separated from the source code, for the MatLab. The documentation generators, apart from the standard functionalities, offer many additional tools, like: • Graphs drawing; • Fitting of the output formats for the components according to the user’s demand; • Underlining and lighting with colors the key words [2-40, 45, 46]. One of the additional functionalities of the documentation generators is drawing of graphs. The graphs present in a hermetic way the code structure, all embedded dependencies, sequence of the called functions in a descending or ascending way. A particularly useful possibility is to generate the graphs which are in agreement with the UML standard. The most frequently generated graphs are inheritance diagrams. The most flexible generators of this kind are the following applications: ProjectAnalyzer, EnterpriseArchitect and Imagix4D [21, 31, 46]. This paper presents an original, offered as free, documentation generator for the source codes from MatLab and from the VHDL. The application generates additionally class graphs in agreement with the UML standard. Proc. of SPIE Vol. 8010 80100R-2 Downloaded from SPIE Digital Library on 25 Jun 2011 to 194.29.135.8. Terms of Use: http://spiedl.org/terms 2. FUNCTIONAL DESIGN OF GENERATOR Realization of the Project was divided to three stages: choice of a basic documentation generator, supplementing the generator with support for the VHDL and MatLab languages, adding a generator of class graphs compatible with the UML standard for the listed languages. The functional diagram of the designed generator was presented in fig.1. Base Support for UML class VHDL