Documentation Generators: Internals of Doxygen John Tully.

Slides:



Advertisements
Similar presentations
An Introduction to GATE
Advertisements

DOCUMENT TYPES. Digital Documents Converting documents to an electronic format will preserve those documents, but how would such a process be organized?
Java Script Session1 INTRODUCTION.
Lecture 3 Getting Started with ITK!. Goals for this lecture Learn how to use Cmake Build ITK Example programs that use ITK.
CPSC Compiler Tutorial 9 Review of Compiler.
Information Retrieval in Practice
Server-Side vs. Client-Side Scripting Languages
DT228/3 Web Development JSP: Directives and Scripting elements.
Russell Taylor Lecturer in Computing & Business Studies.
About the Presentations The presentations cover the objectives found in the opening of each chapter. All chapter objectives are listed in the beginning.
1 Java Server Pages Can web pages be created specially for each user? What part does Java play?
Information Extraction from Documents for Automating Softwre Testing by Patricia Lutsky Presented by Ramiro Lopez.
Chapter 3 Planning Your Solution
Overview of Search Engines
Doxygen and Javadoc By Derzsy Noemi.
DEiXTo.
2440: 141 Web Site Administration Web Server-Side Programming Professor: Enoch E. Damson.
UNIT-V The MVC architecture and Struts Framework.
Doxygen: Source Code Documentation Generator John Tully.
Concordia University Department of Computer Science and Software Engineering Click to edit Master title style ADVANCED PROGRAMING PRACTICES API documentation.
CLARIN tools for workflows Overview. Objective of this document  Determine which are the responsibilities of the different components of CLARIN workflows.
WorkPlace Pro Utilities.
Overview of Previous Lesson(s) Over View  ASP.NET Pages  Modular in nature and divided into the core sections  Page directives  Code Section  Page.
Working Out with KURL! Shayne Koestler Kinetic Data.
Copyright © 2012 Accenture All Rights Reserved.Copyright © 2012 Accenture All Rights Reserved. Accenture, its logo, and High Performance Delivered are.
XSLT for Data Manipulation By: April Fleming. What We Will Cover The What, Why, When, and How of XSLT What tools you will need to get started A sample.
Getting Started with ANTLR Chapter 1. Domain Specific Languages DSLs are high-level languages designed for specific tasks DSLs include data formats, configuration.
CNIT 133 Interactive Web Pags – JavaScript and AJAX JavaScript Environment.
Parser-Driven Games Tool programming © Allan C. Milne Abertay University v
Chapter 10: Compilers and Language Translation Invitation to Computer Science, Java Version, Third Edition.
DBSQL 14-1 Copyright © Genetic Computer School 2009 Chapter 14 Microsoft SQL Server.
Introduction to Applets CS 3505 Client Side Scripting with applets.
JavaDoc1 JavaDoc DEPARTMENT OF COMPUTER SCIENCE AND SOFTWARE ENGINEERING CONCORDIA UNIVERSITY July 24, 2006 by Emil Vassev & Joey Paquet revision 1.2 –
Chapter 2 Architecture of a Search Engine. Search Engine Architecture n A software architecture consists of software components, the interfaces provided.
Program documentation Using the Doxygen tool Program documentation1.
1 3. Computing System Fundamentals 3.1 Language Translators.
Copyrighted material John Tullis 10/17/2015 page 1 04/15/00 XML Part 3 John Tullis DePaul Instructor
Unit-1 Introduction Prepared by: Prof. Harish I Rathod
Flex: A fast Lexical Analyzer Generator CSE470: Spring 2000 Updated by Prasad.
UHD::3320::CH121 DESIGN PHASE Chapter 12. UHD::3320::CH122 Design Phase Two Aspects –Actions which operate on data –Data on which actions operate Two.
Selenium and Selenium on Rails. Agenda  Overview of Selenium Simple Selenium Tests Selenium IDE  Overview of Selenium on Rails  Problems with Selenium.
Towards the better software metrics tool motivation and the first experiences Gordana Rakić Zoran Budimac.
JavaScript Syntax, how to use it in a HTML document
Chapter 1 Introduction. Chapter 1 - Introduction 2 The Goal of Chapter 1 Introduce different forms of language translators Give a high level overview.
CS 460/660 Compiler Construction. Class 01 2 Why Study Compilers? Compilers are important – –Responsible for many aspects of system performance Compilers.
Computing System Fundamentals 3.1 Language Translators.
ASP (Active Server Pages) by Bülent & Resul. Presentation Outline Introduction What is an ASP file? How does ASP work? What can ASP do? Differences Between.
– Intermediate Perl 1/6/ Intermediate Perl - POD, parameters and configuration Intermediate Perl – Session 7 · POD –
ASP. ASP is a powerful tool for making dynamic and interactive Web pages An ASP file can contain text, HTML tags and scripts. Scripts in an ASP file are.
Cross Language Clone Analysis Team 2 February 3, 2011.
JavaScript 101 Introduction to Programming. Topics What is programming? The common elements found in most programming languages Introduction to JavaScript.
Concepts and Realization of a Diagram Editor Generator Based on Hypergraph Transformation Author: Mark Minas Presenter: Song Gu.
ANU comp2110 Software Design lecture 10 COMP2110 Software Design in 2004 lecture 10 Software Architecture 2 of 2 design lecture 5 of 6 Goal of this small.
Chapter – 8 Software Tools.
1 Asstt. Prof Navjot Kaur Computer Dept PRESENTED BY.
Semantic Wiki: Automating the Read, Write, and Reporting functions Chuck Rehberg, Semantic Insights.
Preface IIntroduction Course Objectives I-2 Course Content I-3 1Introduction to Oracle Reports Developer Objectives 1-2 Business Intelligence 1-3 Enterprise.
Lecture Transforming Data: Using Apache Xalan to apply XSLT transformations Marc Dumontier Blueprint Initiative Samuel Lunenfeld Research Institute.
Your Interactive Guide to the Digital World Discovering Computers 2012 Chapter 13 Computer Programs and Programming Languages.
1 Doxygen. 2 Doxygen: What is it ? ● A documentation generator – for C++, C, Java, Objective-C, Python, IDL (Corba and Microsoft flavors), Fortran, VHDL,
Problem Solving With C++ Doxygen Oct/Nov Introduction Doxygen is a documentation generator, a tool for writing software reference documentation.
Information Retrieval in Practice
Doxygen.
PRINCIPLES OF COMPILER DESIGN
Search Engine Architecture
Documentation Generators
-by Nisarg Vasavada (Compiled*)
ASP.NET Imran Rashid CTO at ManiWeber Technologies.
Chapter 10: Compilers and Language Translation
Consuming Web Services with 2E Generated Objects
Presentation transcript:

Documentation Generators: Internals of Doxygen John Tully

Motivation: Why document code? Required by company / administrators who examine code Required by company / administrators who examine code Typically in software engineering, code isn’t consistently worked on Typically in software engineering, code isn’t consistently worked on Co-workers (or “smart” users) look at source code for a better understanding of functionality Co-workers (or “smart” users) look at source code for a better understanding of functionality Code modified/built upon by others Code modified/built upon by others

Motivation: Why Automated? Docs much more likely to be up to date - developers only need to update comments in code (editing word docs/latex files isn’t enjoyable) Docs much more likely to be up to date - developers only need to update comments in code (editing word docs/latex files isn’t enjoyable) Reuse of comments = ½ the work Reuse of comments = ½ the work Auto formatting Auto formatting More importantly, automatic cross-referencing if the automated system is sophisticated More importantly, automatic cross-referencing if the automated system is sophisticated Huge advantage: what if recipients want different formats? Huge advantage: what if recipients want different formats? Management team (or dumb readers) Management team (or dumb readers) End users End users Software testers or other software developers Software testers or other software developers

Problem / Goals Create a simple, easy-to-use, portable, highly configurable automatic documentation generator for a variety of output formats Create a simple, easy-to-use, portable, highly configurable automatic documentation generator for a variety of output formats Real motivation: Creator (Dimitri Van Heesch) used Qt, an application development framework (popular for creating GUIs) Real motivation: Creator (Dimitri Van Heesch) used Qt, an application development framework (popular for creating GUIs) Wrote docs by hand to look exactly like Qt documentation; tried doc++ to do this automatically (not configurable enough) Wrote docs by hand to look exactly like Qt documentation; tried doc++ to do this automatically (not configurable enough) source: sourceforge

Other Doc Generators Several generators support more languages than Doxygen * Several generators support more languages than Doxygen * ROBODoc, TwinText, Natural Docs ROBODoc, TwinText, Natural Docs VB, Pascal,.NET, Perl, JavaScript, SQL VB, Pascal,.NET, Perl, JavaScript, SQL Many (including Doxygen) allow addition of new languages Many (including Doxygen) allow addition of new languages Discussion – ease use of these tools? Discussion – ease use of these tools? As far as output formats, Doxygen most versatile As far as output formats, Doxygen most versatile Also seems to be best for diagram generation Also seems to be best for diagram generation Dependency graphs, inheritance / collaboration diagrams Dependency graphs, inheritance / collaboration diagrams Certain tools may do some things that Doxygen can’t (control flow, data flow); but they’re language-specific Certain tools may do some things that Doxygen can’t (control flow, data flow); but they’re language-specific * Source for info on other generators: Wikipedia

Doxygen Information Flow Source Code Custom Stuff: - Headers - Footers - Images Doxywizard GUI Doxygen Doxyfile (Config file) Tag file Doxytag Program HTML Pages Man Pages RTF Files Latex Files XML ps or pdf MS-Word formatted dox xml parser (for custom output) external docs Source: Doxygen “Getting Started” Page

1. Documentation Source Code Custom Stuff: - Headers - Footers - Images Doxywizard GUI Doxygen Doxyfile (Config file) Tag file Doxytag Program HTML Pages Man Pages RTF Files Latex Files XML ps or pdf MS-Word formatted dox xml parser (for custom output) external docs

2. Configuration Source Code Custom Stuff: - Headers - Footers - Images Doxywizard GUI Doxygen Doxyfile (Config file) Tag file Doxytag Program HTML Pages Man Pages RTF Files Latex Files XML ps or pdf MS-Word formatted dox xml parser (for custom output) external docs

3. Parsing / Execution Source Code Custom Stuff: - Headers - Footers - Images Doxywizard GUI Doxygen Doxyfile (Config file) Tag file Doxytag Program HTML Pages Man Pages RTF Files Latex Files XML ps or pdf MS-Word formatted dox xml parser (for custom output) external docs

4. Output Options Source Code Custom Stuff: - Headers - Footers - Images Doxywizard GUI Doxygen Doxyfile (Config file) Tag file Doxytag Program HTML Pages Man Pages RTF Files Latex Files XML ps or pdf MS-Word formatted dox xml parser (for custom output) external docs

Doxygen Internals Doxygen Information Flow: high-level view of steps taken by the user to document code Doxygen Information Flow: high-level view of steps taken by the user to document code Doxygen Internals: overview of data flow as source files are parsed by Doxygen Doxygen Internals: overview of data flow as source files are parsed by Doxygen Closer look at Parsing / Execution Phase mentioned previously Closer look at Parsing / Execution Phase mentioned previously

Doxygen Internals: Data Flow Config parser: processes configuration file Config parser: processes configuration file Written in flex Written in flex Simple (since config options are pretty simple – just 5 types) Simple (since config options are pretty simple – just 5 types) C Preprocessor: fairly similar to standard preprocessor C Preprocessor: fairly similar to standard preprocessor Written in flex; uses yacc-based parser for expression evaluation Written in flex; uses yacc-based parser for expression evaluation Language parser: convert input buffer into a tree of entries Language parser: convert input buffer into a tree of entries Basically breaks up code into smaller modules that will be reorganized later Basically breaks up code into smaller modules that will be reorganized later Config Parser C Preprocessor Data Organizer Output Generators Source Parser Language Parser Documentation Parser Source: Doxygen“internals” page

Doxygen Internals: Data Flow Data organizer: Gather information from these entries Data organizer: Gather information from these entries Build dictionaries of classes, files, variables, functions, groups, etc. Build dictionaries of classes, files, variables, functions, groups, etc. Determine relationships between these entities Determine relationships between these entities Documentation parser: find comment blocks / tags in entities; feed results to output generators Documentation parser: find comment blocks / tags in entities; feed results to output generators Source parser (if source is documented): cross-referencing, syntax highlighting Source parser (if source is documented): cross-referencing, syntax highlighting Output generators: take data, which was found by language parser and organized/cross- referenced by data organizer, and generate output in specified format Output generators: take data, which was found by language parser and organized/cross- referenced by data organizer, and generate output in specified format Config Parser C Preprocessor Data Organizer Output Generators Source Parser Language Parser Documentation Parser

Debugging Doxygen For a thorough understanding of doxygen’s source code, understanding of flex important For a thorough understanding of doxygen’s source code, understanding of flex important Lexical analyzer: generates scanners (programs that recognize lexical patterns in text) Lexical analyzer: generates scanners (programs that recognize lexical patterns in text) Executable produced from scanners, which execute C code when patterns are found Executable produced from scanners, which execute C code when patterns are found Flex has debugging option to output matched rules when they’re found – easy to follow the steps doxygen is taking Flex has debugging option to output matched rules when they’re found – easy to follow the steps doxygen is taking On internals page, a tool (script) is available which turns on debugging for any flex file On internals page, a tool (script) is available which turns on debugging for any flex file

Limitations / Future Work Limitations / “wish list” of doxygen discussed during demo Limitations / “wish list” of doxygen discussed during demo More languages, more output formats, better template files More languages, more output formats, better template files Several improvements to internals also mentioned: Several improvements to internals also mentioned: Language Parser: Language Parser: One scanner / parser per language (currently one huge combined scanner) One scanner / parser per language (currently one huge combined scanner) Modulate parsing (documentation blocks vs code) Modulate parsing (documentation blocks vs code) Parse preprocessor input for extended documentation (i.e. #defines) Parse preprocessor input for extended documentation (i.e. #defines)

Limitations / Future Work Output generators – interesting future work Output generators – interesting future work Instead of using data structures (generated from the data organizer) to produce XML, use XML as an intermediate language Instead of using data structures (generated from the data organizer) to produce XML, use XML as an intermediate language More info could be extracted by various output generators – with more understandable IL, easy to create better end tools More info could be extracted by various output generators – with more understandable IL, easy to create better end tools Interactive source browsers Interactive source browsers Configurable class diagram generators Configurable class diagram generators Computing code metrics Computing code metrics

Discussion