# Documentation of source codes with the LaTeX package documentation+
Footnote †: This document is the version v0.1, 2011/11/28.

Omar Salazar Morales

Laboratory for Automation, Microelectronics

and Computational Intelligence

Universidad Distrital Francisco Jose de Caldas

Engineering department

Bogota, Colombia

osalazarm@correo.udistrital.edu.co

[http://www.udistrital.edu.co](http://www.udistrital.edu.co)

###### Abstract

This document shows the LaTeX implementation of the package documentation. This package is intended for all software's writers who want to document their source codes by using the comments of the programming language. The source files are processed with LaTeX in order to generate the documentation of them.

###### Contents

* 1 Introduction
* 2 Docstrip modules
* 3 How to use
* 4 Options
* 5 How it works
* 6 Implementation
	* 6.1 Package's identification
	* 6.2 Preliminaries
	* 6.3 Options
	* 6.4 The source code

Introduction

On environments of software development is necessary to make the documentation of the source code according to its last modification. Sometimes, this is not easy, because of _documentation_ and _source code_ are written on different files.

In order to avoid this situation, where a software maker have to write two different files, LaTeX gives the possibility to handle an unique file where source code and documentation are together. Through the documentation package a software maker can write the source code for his application, and inside of its comments, he can document it. It's only neccessary to put LaTeX commands inside the comments of the source files. Source files are then proccesed by LaTeX to get a beautiful document (PDF, DVI, PS,...)

The real advantage of this technique is that LaTeX will be present to handle all the documentation. If a software maker wants to put a complex formula where he explains a difficult algorithm, then he will be able to do it in the usual way with LaTeX commands.

## 2 Docstrip modules

This package has been developed with the typical LaTeX's documentation techniques. Docstrip has been used for the preparation of the source code of the package and its documentation.

The following docstrip modules were implemented to generate the different files of this project.

\usepackage This package is used in the usual way. You should use the \usepackage command in the preamble of your master's documentation file as follows \usepackage[<options>]{documentation} The <options> are presented in the next section.

## 4 Options

java java option is used when JAVA language is used. In this programming language the comment's character is // when one-line's comments are needed. If multi-line's comments are needed then /* and */ are neccessary. Then, all the comments inside your JAVA code have to start with //, or to be enveloped with /* and */.

c option is used when C language is used (or any of its variants like C++


// // More comments with \LaTeX{} commands... // // //begin{sourcecode} void main (void) { printf("Hello world!\n"); // "Hello world" message } //\end{sourcecode} /* / More comments with \LaTeX{} commands... */ In C or JAVA you can use // or /* and */ to add comments, but you have to use // before \begin{sourcecode} and \end{sourcecode}.
4. You can add a master's documentation file (*.tex) in your IDE. In the preamble of this file you have to use \usepackage[<options>]{documentation}. Now, you can read all your source files of your project with the LaTeX command \inputsourcecode{<source file>} where <source file> is the path of your source file with its extension2. Footnote 2: Extension is needed because of some IDEs create different files with the same name and different extensions

For the previous example, this file looks like

 %  % This is dochelloword.tex  %  %documentclass{article}  %uspackage[c]{documentation} % Needed  %begin{document}  %inputsourcecode{helloworld.c} % input your source code \end{document} You can use any LaTeX class (for example, article, book, report,...) and any number of \inputsourcecode commands in order to read any number of source files.
5. Run LaTeX as usual to get the documentation of your source code. In the previous example, run dochelloword.tex through LaTeX. \inputsourcecode will read your source files and it will extract the documentation from the comments.

Implementation

### Package's identification

\NeedsTeXFormatPackagedocumentationwascreatedtouseitwith LaTeX2\({}_{\_}\).

\ProvidesPackage1%<*sty>

2\NeedsTeXFormat{LaTeX2e}%

3\ProvidesPackage{documentation}%

4[2011/11/28v0.1Makethedocumentationforyoursourcecode]%

### Preliminaries

\ifDOC@javalang

\ifDOC@Clamg

\ifDOC@Clamg

\ifDOC@assemblerlang

\ifDOC@assemblerlang

\ifDOC@javalang

\ifDOC@Clamg

C (or C++ and C#)

\ifDOC@assemblerlang

Thesevariablesbeginwithafalsevalue.

5\newif\ifDOC@javalang

\DOC@Clamg

\newif\ifDOC@assemblerlang\DOC@assemblerlangfalse

### Options

java option calls all the necessary code which is needed to make the documentation for JAVA language. This programming language uses the comment's characters // for one-line's comments and /*...*/ for multi-line's comments.

This option gives true value to \ifDOC@javalang and false to others. Inside this option, \DOC@Changeccofcommentchar and \DOC@definecsofcommentchar are defined in order to change the \catcode of / and * as desire, and to define the macros \/ and \* to print / and * inside the text of the source files.

\DeclareOption{java}%

\DOC@javalangtrue\DOC@Clamgfalse

\DOC@assemblerlangfalse

\gdef\DOC@changeccofcommentchar#1{\catcode'/=#1}

\gdef\DOC@definecsofcommentchar{\chardef\/='/

\gdef\DOC@changeccofcommentchar#1{\catcode'/=#1}%

\gdef\DOC@definecsofcommentchar{\chardef\/='/

\gdef\DOC@changeccofcommentchar#1{\catcode'/=#1}%

\gdef\DOC@changeccofcommentchar#1{\catcode'/=#1}

\cactode'*=#1}%
20\gdef\DOC@definecsoformmentchar{\chardef\/='/
21\chardef\*='*}%
22assemblerassembleroptioncallsallthenecessarycodewhichisneededtomakethedocumentationforassemblerlanguage.Thisprogramminglanguageusesthemcomment'scharacters;forallkindofcomments.

Thisoptiongivestruevalueto\ifDOC@assemblerlangandfalsetoothers.Insidethisoption,\DOC@changeccofcommentcharand\DOC@definecsofcommentchararedefinedinordertochangethe\cactodeof;asdesire,andtodefinethemacro\;toprint;insidethetextofthesourcefiles.
22\DeclareOption{assembler}{%
23\DOC@javalangfalse\DOC@Clangfalse
24\DOC@assemblerlangtrue
25\gdef\DOC@changeccofcommentchar#1{\cactode';=#1}%
26\gdef\DOC@definecsoformmentchar{\chardef\;=';}}%

Alltheotheroptionswhicharespecifiedbytheuser,butwhicharenotdefined,giveanerrormessageas_unknownoptions._
27\DeclareOption*{%
28\PackageError{documentation}%
29{Unknownoption'\currentOption'}%
30{Seethedocumentationformoredetails}}%

Now,it'snecessarytoprocessalltheoptionswhichwerespecifiedbytheuser.coptionisusedasthedefault.
31\ExecuteOptions{c}\ProcessOptions\relax

### The source code

``` sourcecode\begin{sourcecode}and\end{sourcecode}isthewayasanusergivesthesourcecodeforhisapplication.Allsourcecodehastobeenvelopedwiththisenvironmentinordertowriteitverbatim.Therealdifferencewithrespecttoverbatimisthatsourcescoderecognizesthecomment'scharacteroftheprogramminglanguage.Thisenvironmentpermitstowritethecomment'scharacterinsidewithoutanyspecial LaTeXcommand(like\/,\* or\;;).Theonlyrestrictionisthatyouhavetousethemoment'scharacterofyourprogramminglanguagejustbefore\begin{sourcecode}and\end{sourcecode}_withoutspaces_betweenthem.sourcescodeusestheinternalmacros\@verbatim,\frenchspacing,\@vobeypspaces,\if@newlist,\leavevmodeand\end{verbtirivlist.Seeltmiscen.dtxformoredetails.
32\def\sourcecode{\DOC@changeccofcommentchar{12}%
33\@verbatim\frenchspacing\@vobeypspaces\DOC@sourcecode}%
34\def\end{sourcecode{\if@newlist\leavevmode\if\endtrivlist}%
35\DOC@sourcecode recognizesthebeginningandtheendoftherealsourcecodebyusingthemcomment'scharacterofyourprogramminglanguage.Then,thismacrosdepends on the language. This macro begins changing some \catcodes of some characters because it's needed to say to LaTeX where is the end of the source code. This is done inside a group because it's needed to keep local all changes.

```
35\begingroup
36\catcode'|=0\catcode'[=1
37\catcode']=2\catcode'\{=12
38\catcode'\=12\catcode'\=12
39|catcode'/=12|catcode';=12
```

Now, \DOC@sourcecode is defined according to the language. It's needed to say to LaTeX that source code will finish with the comment's character of the programming language which is followed by \end{sourcecode}_without spaces_. At the end, the group is closed.

```
40|ifDOC@javalang
41|gdef|DOC@sourcecode#1//\end{sourcecode}[#1|end[sourcecode]]%
42|fi
43|ifDOC@Clang
44|gdef|DOC@sourcecode#1//\end{sourcecode}[#1|end[sourcecode]]%
45|fi
46|ifDOC@assemblerlang
47|gdef|DOC@sourcecode#1;\end{sourcecode}[#1|end[sourcecode]]%
48|fi
49|endgroup
```

This is the way as an user \inputs his source code. This command uses the classical \input LaTeX command. It begins with the definition of \DOC@path as the path of the source file. \DOC@path is necessary because of UNIX systems use / as a delimiter on its directory tree (for example /usr/share/local/), and JAVA and C use the same character as comment's character. Everything is done inside a group.

```
50\def\inputsourcecode#1\begingroup
52\def\DOC@path{#1}%
```

Now, it's time to define the right command secuence if an user wants to print the comment's character inside the documentation, also, it's changed the \catcode of the comment's character which is treated as an space (catcode 10).

```
53\DOC@definecsofcommentchar
54\DOC@changeccofcommentchar{10}%
```

At the end, the source file is red. Notice that \inputsourcecode keeps all changes local. Then, your source file doesn't affect any other part of your LaTeX document.

```
55\expandafter\input\DOC@path
56\endgroup%
57\/\sty\

## Chapter 1 Change History

v0.1

General: Initial version