DOCSLIB.ORG

Documentation Generator for VHDL and Matlab Source Codes for Photonic and Electronic Systems

Total Page：16

File Type：pdf, Size：1020Kb

Download full-text PDF Read full-text
Documentation Generator for VHDL and Matlab Source Codes for Photonic and Electronic Systems 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
Load more

Recommended publications
  • Doxydoxygen User Guide Release 0.79.4
    DoxyDoxygen User Guide Release 0.79.4 20Tauri Aug 16, 2021 MANUAL 1 Welcome to DoxyDoxygen 1 2 Installation 3 2.1 Software installation with Package Control...............................3 2.2 Manual software installation.......................................3 2.3 License installation............................................4 2.4 EULA (End User License Agreement)..................................4 2.4.1 Licenses.............................................4 2.4.2 Description of other rights and limitations...........................4 2.4.3 No warranties..........................................5 3 Usage 7 3.1 Create a documentation block......................................7 3.2 Update / wrap an existing documentation block.............................8 3.3 Switch between comment styles.....................................9 3.4 Extend a documentation block......................................9 3.4.1 Auto-completion........................................9 3.4.2 Comment continuation..................................... 10 3.5 Navigate in documentation........................................ 10 3.5.1 Move to the right column.................................... 10 3.5.2 Follow references........................................ 10 3.6 Fold / Unfold comments......................................... 11 3.7 Translate................................................. 11 3.8 Generate documentation......................................... 12 4 Customization 13 4.1 Settings.................................................. 13 4.1.1 Understand
    [Show full text]
  • Use of the Protocol Generator
    Manual for the protocol generator Table of contents Manual for the protocol generator.....................................................................................................................1 Introduction..................................................................................................................................................3 Acknowledgements.......................................................................................................................................................3 Preparation and installation..........................................................................................................................4 Preparation for Presentation *.log file before acquiring data........................................................................................4 Installation......................................................................................................................................................................5 Using the protocol generator........................................................................................................................6 Activating the plugin......................................................................................................................................................6 Main menu.....................................................................................................................................................................7 Option 1: generating a protocol file..............................................................................................................8
    [Show full text]
  • Java Code Documentation Example
    Java Code Documentation Example Fruitless Martino sometimes quick-freeze his peritonitis hugely and night-club so dispraisingly! Glottogonic and sublinear Finn melt his bodice permeates podding benevolently. Oswald usually medicines surgically or orbs telescopically when polyunsaturated Hugh dement evidentially and lewdly. The javadoc itself an unsupported extension and is also important in the description for code documentation comment merely repeats the banner section DocsapijavanetURLhtmlgetAuthority-- a method getAuhority in the. API reference code comments Google Developers. Omitting many times classes being documented type, and java example of each field, all trademarks and description below code completion window, which we used to. Java Programming Style Guide. The keyboard shortcut to comment multiple in Windows is shift alt A. 10 Best Practices to multiple While Writing Code Javarevisited. Concise presentations of java programming practices tasks and conventions amply illustrated with syntax highlighted code examples. Java Documentation Comments Tutorialspoint. Java Programming Guidelines. If this tag easily comment related comments java code, this user to new field in the dependency. The following examples demonstrate a pain line summary followed by detailed documentation in song three. CS 302 Commenting Guide Program Commenting Guide File. For sober you spawn use author tag to identify the author of a. Opinions expressed by the code example code documentation is overridden in the documentation for example code base classes and decide to allow bikes to achieve these methods. Example slope from the Javadoc documentation code can be documented inline Single Line comments are started by each may be positioned after a. The Documentation Comment Specification permits leading asterisks on enough first.
    [Show full text]
  • The Types, Roles, and Practices of Documentation in Data Analytics Open Source Software Libraries
    Computer Supported Cooperative Work (CSCW) https://doi.org/10.1007/s10606-018-9333-1 © The Author(s) 2018 The Types, Roles, and Practices of Documentation in Data Analytics Open Source Software Libraries A Collaborative Ethnography of Documentation Work R. Stuart Geiger1 , Nelle Varoquaux1,2 , Charlotte Mazel-Cabasse1 & Chris Holdgraf1,3 1Berkeley Institute for Data Science, University of California, Berkeley, 190 Doe Library, Berkeley, CA, 94730, USA (E-mail: [email protected]); 2Department of Statistics, Berkeley Institute for Data Science, University of California, Berkeley, Berkeley, CA, USA; 3Berkeley Institute for Data Science, Helen Wills Neuroscience Institute, University of California, Berkeley, Berkeley, CA, USA Abstract. Computational research and data analytics increasingly relies on complex ecosystems of open source software (OSS) “libraries” – curated collections of reusable code that programmers import to perform a specific task. Software documentation for these libraries is crucial in helping programmers/analysts know what libraries are available and how to use them. Yet documentation for open source software libraries is widely considered low-quality. This article is a collaboration between CSCW researchers and contributors to data analytics OSS libraries, based on ethnographic fieldwork and qualitative interviews. We examine several issues around the formats, practices, and challenges around documentation in these largely volunteer-based projects. There are many dif- ferent kinds and formats of documentation that exist around such libraries, which play a variety of educational, promotional, and organizational roles. The work behind documentation is similarly multifaceted, including writing, reviewing, maintaining, and organizing documentation. Different aspects of documentation work require contributors to have different sets of skills and overcome various social and technical barriers.
    [Show full text]
  • Headerdoc Unfettered
    HeaderDoc Unfettered May 27, 2004 CDB is a trademark of Third Eye Software, Apple Computer, Inc. Inc. © 1999, 2004 Apple Computer, Inc. Helvetica is a trademark of Heidelberger All rights reserved. Druckmaschinen AG, available from Linotype Library GmbH. No part of this publication may be reproduced, stored in a retrieval system, or Java and all Java-based trademarks are transmitted, in any form or by any means, trademarks or registered trademarks of Sun mechanical, electronic, photocopying, Microsystems, Inc. in the U.S. and other recording, or otherwise, without prior countries. written permission of Apple Computer, Inc., Simultaneously published in the United with the following exceptions: Any person States and Canada. is hereby authorized to store documentation Even though Apple has reviewed this manual, on a single computer for personal use only APPLE MAKES NO WARRANTY OR and to print copies of documentation for REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS MANUAL, personal use provided that the ITS QUALITY, ACCURACY, documentation contains Apple's copyright MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. AS A RESULT, THIS notice. MANUAL IS SOLD ªAS IS,º AND YOU, THE PURCHASER, ARE ASSUMING THE ENTIRE The Apple logo is a trademark of Apple RISK AS TO ITS QUALITY AND ACCURACY. Computer, Inc. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, Use of the ªkeyboardº Apple logo OR CONSEQUENTIAL DAMAGES (Option-Shift-K) for commercial purposes RESULTING FROM ANY DEFECT OR without the prior written consent of Apple INACCURACY IN THIS MANUAL, even if advised of the possibility of such damages.
    [Show full text]
  • What I Wish I Knew When Learning Haskell
    What I Wish I Knew When Learning Haskell Stephen Diehl 2 Version This is the fifth major draft of this document since 2009. All versions of this text are freely available onmywebsite: 1. HTML Version ­ http://dev.stephendiehl.com/hask/index.html 2. PDF Version ­ http://dev.stephendiehl.com/hask/tutorial.pdf 3. EPUB Version ­ http://dev.stephendiehl.com/hask/tutorial.epub 4. Kindle Version ­ http://dev.stephendiehl.com/hask/tutorial.mobi Pull requests are always accepted for fixes and additional content. The only way this document will stayupto date and accurate through the kindness of readers like you and community patches and pull requests on Github. https://github.com/sdiehl/wiwinwlh Publish Date: March 3, 2020 Git Commit: 77482103ff953a8f189a050c4271919846a56612 Author This text is authored by Stephen Diehl. 1. Web: www.stephendiehl.com 2. Twitter: https://twitter.com/smdiehl 3. Github: https://github.com/sdiehl Special thanks to Erik Aker for copyediting assistance. Copyright © 2009­2020 Stephen Diehl This code included in the text is dedicated to the public domain. You can copy, modify, distribute and perform thecode, even for commercial purposes, all without asking permission. You may distribute this text in its full form freely, but may not reauthor or sublicense this work. Any reproductions of major portions of the text must include attribution. The software is provided ”as is”, without warranty of any kind, express or implied, including But not limitedtothe warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authorsor copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, Arising from, out of or in connection with the software or the use or other dealings in the software.
    [Show full text]
  • Comments and Documentation 2501ICT/7421Ictnathan
    C Comments Using Doxygen Comments and Documentation 2501ICT/7421ICTNathan René Hexel School of Information and Communication Technology Griffith University Semester 1, 2012 René Hexel Comments and Documentation C Comments Using Doxygen Outline 1 C Comments 2 Using Doxygen René Hexel Comments and Documentation C Comments Using Doxygen Comments Plain C allows comments between /* and */ /* this is a valid C comment */ Comments may not be nested /* this /* is not a valid C comment */ */ C99 also allows double-slash // end-of-line comments // this is a valid comment no closing sequence needed – the comment ends at the end of the line René Hexel Comments and Documentation C Comments Using Doxygen Comment Example Example (Program with Comments) /* * This program prints "j = 007". * It does not take any parameters and returns 0 on success. */ int main(void)/ * main function definition */ { int j; // our int variable to play with j=7; // assign a value to be printed printf("j = %03.3dnn",j); // print value with leading zeroes return 0; // everything is fine, exit program } René Hexel Comments and Documentation C Comments Using Doxygen Where to put comments? At the beginning of each file (module) describe the name of the module, purpose, author, and dates when first created and last modified Before each function (method) describe the purpose of the function or method, input parameters (arguments), return values (output parameters), and pre- and postconditions (contract) At the beginning of each class describe the purpose of the class, and things to
    [Show full text]
  • Dragonfly.Wpi.Edu/Book/ February 28, 2013 8:8 Computer Science Education Paper
    February 28, 2013 8:8 Computer Science Education paper Computer Science Education Vol. XX, No. XX, June 2013, 1–18 RESEARCH ARTICLE Dragonfly – Strengthening Programming Skills by Building a Game Engine from Scratch Mark Claypool Computer Science and Interactive Media & Game Development Worcester Polytechnic Institute, Worcester, MA 01609, USA email: [email protected] (Received 00 Month 200x; final version received 00 Month 200x) Computer game development has been shown to be an effective hook for motivating students to learn both introductory and advanced computer science topics. While games can be made from scratch, to simplify the programming required game development often uses game engines that handle complicated or frequently used components of the game. These game engines present the opportunity to strengthen programming skills and expose students to a range of fundamental computer science topics. While educational efforts have been effective in using game engines to improve computer science education, there have been no published papers describing and evaluating students building a game engine from scratch as part of their course work. This paper presents the Dragonfly-approach in which students build a fully functional game engine from scratch and make a game using their engine as part of a junior-level course. Details on the programming projects are presented, as well as an evaluation of the results from two offerings that used Dragonfly. Student performance on the projects as well as student assessments demonstrate the efficacy of having students build a game engine from scratch in strengthening their programming skills. Keywords: game engine, programming, object-oriented design, software engineering, game development 1 Introduction By the end of their second year, most computer science students have been exposed to a breadth of foundational materials, such as introductory programming, basic data structures and algo- rithms, and have begun to write programs of moderate size – hundreds of lines of code, perhaps up to even a thousand lines of code.
    [Show full text]
  • Not All Patterns, but Enough
    Not All Patterns, But Enough Neil Mitchell, Colin Runciman York University Catch An Example • Is the following code safe?* risers :: Ord α→[α] → [[α]] risers [] = [] risers [x] = [[x]] risers (x:y:etc) = if x ≤ y then (x:s) : ss else [x] : (s : ss) where s:ss = risers (y : etc) > risers “Haskell” = [“Has”,“k”,“ell”] * Only people who haven’t seen this example in the paper! Using Catch > catch risers.hs Incomplete pattern on line 6 Program is safe • Catch is the associated implementation • Catch has proven the program is safe • Without any annotations The Pattern-Matching problem • Will a program crash when run? • May call error directly: error “doh!” • May call error indirectly: head [] • Partial pattern match: case False of True → 1 • GHC can warn on partial patterns • Catch conservatively checks a program will not crash at runtime • Even in the presence of partial patterns How Catch works First convert Haskell to first-order Core, using Yhc and Firstify Checker Exact Operates on first-order (ignoring laziness) Core language 3 constraint operators Constraint Language Conservative Describes a (possibly infinite) set of values Can replace constraint language Checker Terms • A constraint describes a set of values • x is a (:)-constructed value • A precondition is a constraint on arguments • In head x, x must be (:)-constructed • An entailment is a constraint on arguments to ensure a constraint on the result • If x is (:)-constructed, null x is False Checker Types • Opaque constraint type • data Constraint = … • Does an expression satisfy
    [Show full text]
  • PHP Beyond the Web Shell Scripts, Desktop Software, System Daemons and More
    PHP Beyond the web Shell scripts, desktop software, system daemons and more Rob Aley This book is for sale at http://leanpub.com/php This version was published on 2013-11-25 This is a Leanpub book. Leanpub empowers authors and publishers with the Lean Publishing process. Lean Publishing is the act of publishing an in-progress ebook using lightweight tools and many iterations to get reader feedback, pivot until you have the right book and build traction once you do. ©2012 - 2013 Rob Aley Tweet This Book! Please help Rob Aley by spreading the word about this book on Twitter! The suggested hashtag for this book is #phpbeyondtheweb. Find out what other people are saying about the book by clicking on this link to search for this hashtag on Twitter: https://twitter.com/search?q=#phpbeyondtheweb Contents Welcome ............................................ i About the author ...................................... i Acknowledgements ..................................... ii 1 Introduction ........................................ 1 1.1 “Use PHP? We’re not building a website, you know!”. ............... 1 1.2 Are you new to PHP? ................................. 2 1.3 Reader prerequisites. Or, what this book isn’t .................... 3 1.4 An important note for Windows and Mac users ................... 3 1.5 About the sample code ................................ 4 1.6 External resources ................................... 4 1.7 Book formats/versions available, and access to updates ............... 5 1.8 English. The Real English. .............................. 5 2 Getting away from the Web - the basics ......................... 6 2.1 PHP without a web server .............................. 6 2.2 PHP versions - what’s yours? ............................. 7 2.3 A few good reasons NOT to do it in PHP ...................... 8 2.4 Thinking about security ...............................
    [Show full text]
  • Haddock User Guide I
    Haddock User Guide i Haddock User Guide Haddock User Guide ii Copyright © 2004 Simon Marlow Haddock User Guide iii COLLABORATORS TITLE : Haddock User Guide ACTION NAME DATE SIGNATURE WRITTEN BY Simon Marlow 2004-08-02 REVISION HISTORY NUMBER DATE DESCRIPTION NAME Haddock User Guide iv Contents 1 Introduction 1 1.1 Obtaining Haddock . .1 1.2 License . .2 1.3 Acknowledgements . .2 2 Invoking Haddock 3 2.1 Using literate or pre-processed source . .6 3 Documentation and Markup 7 3.1 Documenting a top-level declaration . .7 3.2 Documenting parts of a declaration . .8 3.2.1 Class methods . .8 3.2.2 Constructors and record fields . .8 3.2.3 Function arguments . .9 3.3 The module description . .9 3.4 Controlling the documentation structure . .9 3.4.1 Re-exporting an entire module . 10 3.4.2 Omitting the export list . 10 3.5 Named chunks of documentation . 11 3.6 Hyperlinking and re-exported entities . 11 3.7 Module Attributes . 12 3.8 Markup . 12 3.8.1 Paragraphs . 12 3.8.2 Special characters . 12 3.8.3 Character references . 13 3.8.4 Code Blocks . 13 3.8.5 Hyperlinked Identifiers . 13 3.8.6 Emphasis and Monospaced text . 13 3.8.7 Linking to modules . 14 3.8.8 Itemized and Enumerated lists . 14 3.8.9 Definition lists . 14 3.8.10 URLs . 14 3.8.11 Anchors . 14 Haddock User Guide v 4 Index 15 Abstract This document describes Haddock version 2.6.1, a Haskell documentation tool. Haddock User Guide 1 / 15 Chapter 1 Introduction This is Haddock, a tool for automatically generating documentation from annotated Haskell source code.
    [Show full text]
  • Nateguyver Breakpoints LLDB Debug Toolchain More
    ��������������������������� ��������������������������� �������� ����������������������������������������������������������������������������������� ���������������������������������������������������������������������������������������������� ������������������������������������������������������������������������������������������� ������������������������������� ��������������������������������������������������������������������������������������� ����������������������������������������������������������������������� �������������������������������������������������������������������������������������� �������������������������������������������� ◼ Breakpoints & watchpoints ◼ Xcode's graphical debugger ◼ LLDB �������������� “ ������������������������������������������������������������������������������������ ��������������������������� ”������������������ ���������������������������� ◼ Assertions, Logging, and Debug configuration ◼ Static analysis & runtime memory tools ◼ Unit testing in xcode ���������������� ◼ Emphasis on LLDB as our debugging foundation ◼ Tips and tricks to stramline your the debuggin experience ◼ Use LLDB as an extensible investigative tool “�������������”������������ “��’���������������������������������������������������’���������������������’�������������� ��������’����������������������������������� ”������������������ ��������������������������������������������������� ���������������������������������������������������������������������������������� ����������������������������������������������������������������������������
    [Show full text]