ZICDOC - HTML documentation generator for ABAP programs - part I

[Former Member]

1 ZICDOC introduction

1.1 What is ZICDOC generator

ZICDOC is an ABAP program, which ties to analyze source code of other ABAP program and create then HTML documentation. It is based mainly on comments extracted from source code, but it also recognize a few simple objects like database tables, forms, classes and similar code blocks and tries to assign comments to these objects. As a result, you can receive HTML file describing analyzed program. The level of details depend on what programmer "left" in source code.

1.2 Short story

Documenting source code of any program is crucial for it's later maintenance and extending. There are many tools for storing documentation (from word processors and file systems to advanced and sophisticated databases with version management, workflows and other wonderful functionalities).  But programmers don't like to use them. After several program's modification, such a documentation is typically outdated and sooner or later - useless. I see, that the only place where programmers eventually leave additional information is source code (comments).

Suppose, that you have wonderful, detailed and up-to-date information inside source code of your program. That's great, but it isn't the end of you problems. You probably write a program not for yourself. Very soon your manager, quality controller or customer will ask you for any kind of documentation of your work...

It would be nice to have any tool which will automatically create such a documentation based on information in source code. There are several such a tools on the market - JAVADOC is good example, which solves problem of Java programmers. Unfortunately, I have not found such a generator for ABAP (I mean freeware, I heard some time ago about similar tool for ABAP, but it was very expensive).

I have been thinking about automatic documentation generator for several months, but I have had no motivation do it. I have started programming it, but never finished. About one year ago, I have decided finally to go into object-oriented ABAP (learn it) and it was turning point. I was looking for any real task for implementing (not just simple report displaying data from several tables) and I reminded about the generator.

After a few weeks, I had a class analyzing source code and storing results in internal tables. The next step was preparing any solution for displaying these results. At the beginning, I considered creation of XML files and then preparing XML transformations for converting XML data into more readable HTML, PDF or any other format. But, when I looked into details of XMLT - I gave up. It is so complex like new programming language. Finally, I did not decide to learn XML, XMLT and HTML, but just only HTML (it was also new for me). I only introduced CSS (cascade style sheets) to be more flexible with formatting output information.

Now, if you know that the ZICDOC project was for me the first contact with object-oriented ABAP, HTML and CSS, I hope that you will be more patient reading source code of the generator. It still needs some improvements or corrections, but at he moment I have no time to do it.

1.4 SAP R/3 versions

Program was tested mainly on WAS 6.40 and WAS 7.0, but it should work on all versions of WAS. It was also tested a little on 4.6C (I started on this version), but It offers oldest version of statement SCAN ABAP-SOURCE. It has different syntax and results. Source code of the generator contains part described with word COMPATYBILITY (for 4.6C), so it is probably possible to adjust program to that version.

2 Using ZICDOC

2.1 Installation

ATTENTION!
Due to size limit of single Weblog, I had to put source code of programs in part II, III and IV of the blog.

I tried not to use any nonstandard dictionary objects. You can even find, that I haven't used program text for HTML tags, but created them as constants. So, it should be enough just to create all ABAP programs and then activate them. If you want to understand what fields are on selection screen of the main program, copy texts from source code (they are at the beginning ) to selection texts.

Additionally, you have to create file ZIcDocStyle.css.

You should create the following programs:

• ZICDOC - the main program (type ‘1') of the generator. It is ready-to-use program or just example how to call generator from other programs.
• ZICDOC_CL_HTML - include (type ‘I') with class supporting creation of HTML file
• ZICDOC_CL_CODE_ANALYSIS - include containing class for source code analysis
• ZICDOC_CL_CODE_ANALYSIS_HTML - include with class analyzing code and creating HTML documentation

1.1      Starting generator

The main program of generator is ZICDOC. Selection screen is below:

It allows entering the path to generated output HTML file.

As a input you have two options:

• Enter a name of the program in the system (it is suggested). You can try with ZICDOC itself, so you will have documentation of the generator.
• Enter a name and path of file on local disk with source code to be analyzed. This option limits analysis to this single file - any INCLUDES are not taken into account.

Additionally, you can influence the content of generated file (see also section 4). The meaning of options is the following:

• INCLUDES - hierarchy - generates section with a list of includes of the main analyzed program. See: 4.1.
• INCLUDES - details - generates section with information about each include (name, comments, list of code units). See: 4.3.
• Database tables - generates section with a list of database tables accessed from the analyzed program. See: 4.2.
• Class components - generates section with details and components of classes and interfaces. See: 4.4.
• Non-class code units - generates section with list of list events, form, function modules and other code units. See: 4.5.
• Code units hierarchy - generates section with hierarchy of class (for instance one for from another). See: 4.6.
• Protected class components - if protected components have to be placed in output file (in addition do public).
• Private class components - if private components have to be placed in output file (in addition do public).
• Comments include HTML tags - if selected, comments are written to HTML file without any conversion. It allows using formatting tags inside comments (like
  ), but characters like &, <, > can disappear in output file. If you not select this check box, comments are converted to HTML text. Characters like &, <, > are outputted correctly (converted to special strings), but you cannot use HTML tags in your comments.

After starting program, and waiting several seconds, you will (hopefully) see message, that NNNN bytes transferred. It means that your program has been analyzed and you can see results.

Attention!
To see correctly HTML file, you must place in the same folder file with styles: ZIcDocStyle.css. You can find additional information in section 2.6).

1.2 Prerequisites

Before you can create with ZICDOC documentation for any program, the analyzed source code:

• Should be activated (at least syntax check performed). Behavior of the generator during analyzing of code with syntax errors is undefined.
• It is suggested to verify comments in the analyzed code and, if possible, adjust it to standards described in this documents.

1.3 Basic functionality

The generator triesto find comments I source code and assign them to code units (like programs, forms, classes, etc). This information is later used to create documentation for these units. Program recognizes the following types of statements:

• Comments - specials rules apply (see section 3)
• List events - like: START-OF-SELECTION, END-OF-SELECTION, INITIALIZATION, GET, AT.
• Database operation statements - like: TABLES, SELECT, UPDATE, INSERT, MODIFY, DELETE. Based on them, list of tables used in the program can be built. It doses not cover operation performed in function modules called from the program (they are not analyzed).
• Class and interface definition. List of components are built.
• Form definition and call - like FORM, PERFORM
• Report calls - like SUBMIT
• Function module definition - like FUNCTION. The program has not been test for function groups, so it can require improvements.
• Method definition - like METHOD
• Function and methods calls - like CALL xxx (FUNCTION, CUSTOMER-FUNCTION, BADI, METHOD, TRANSACTION).

1.4 Technical description of ZICDOC

I tried to write documentation of the ZICDOC in the source code. Try to generate HTML file for the program (it can be the first exercise). Additional information you will find directly in source code.

In general, the generator is based on built-in keyword SCAN ABAP-CODE (see online help for ABAP). It performs decomposition of source code into single statements and tokens. They can be later analyzed by your own program.

1.5 Cascade Style Sheets

Generation of output HTML file is based on CSS. It allows using simple HTML tags in generated document and storing formatting information in separate file. You can, for instance, have several CSS files with different formatting, and depending on which one is used, different result will be displayed. You can experiment with CSS file and change different options. You can receive quite interesting results.

The name of CSS file is inside HTML file (in the header). The name of file is ZIcDocStyle.css and it must be located in the same directory as the main HTML file. Of course, you can edit HTML file and easy change the name of  used CSS file.

1.5.1  CSS for beginners

CSS files can be edit with dedicated editors (which show you formatting options in dialog windows) or just any plain text editor (like Notepad). In the file, you can assign formatting options (like font name and size, color, table cell width) to specific HTML tags. For instance, headers are displayed with style H1 (in HTML document:

Header text

). In CSS file we define, that this style uses sans-serif font, size of 160% of default, bold and wit additional space before and after. Important thing - if you don't define a specific parameter - it is derived from parent node. It is a little complicated to explain here, but there are many free HTML and CSS courses on WEB.

I have used three basic forms of defining styles (it was an exercise for me):

• Define style for single tags - like for

  to

  ,

  , and others
• Define style for nested tags - used for pair

  . If tag is nested inside

  (inside tables cell) then width of a cell must be equal 25ex. By nesting, I understand:

  Any text in cell

• Define class for tag - used for TD.dbname. This style is used when in HTML document you use.

  Text

2 Comments

Generated documentation is based mainly on comments entered by programmer. This section describes rules, which should be considered.

2.1.1 General rules

Source code comments are very important for understanding usage of functions, forms, objects and individual lines of code. Therefore, program reads comments and places them in output file as description of specific objects.

Depending on a context, comments can describe code before or after it. To assign comments to right objects, strict rules must be applied by a programmer. The most important are described below.

1. All following lines of comments are treated as continuous string and are concatenated into one paragraph (section, segment).  New paragraph starts when:
   - Blank line is between lines of comment (without even *)
   - After any code statement
2. Program assigns single paragraph to specific objects. It means, that if we have several paragraphs (separated by blank lines), only the first or the last will be used. If you want to use blank lines as visual separators inside comments, enter single * at the beginning of the blank line.
3. All comments beginning with " (quotation marks) not in the first column are ignored.
4. All comments, which has 3 the same character starting on 4-th column are ignored (all comments separating parts of code are ignored). Example: *& ---------
5. Program recognizes special comments types. They are cognized by beginning characters of the first line of comment paragraph (details below):
   *& - comment on program level
   *" - comment inside function or other type of coding block (form, method, class)
   * or " - other comment
6. Comments describing programs and includes should start with characters: *& (asterix + ampersand). They are treated in special way - the first appearance of such a comment is assigned to program (include). All others (following) are treated in normal way (like comment before the next statement). As a result, program's description can be placed at the end of the program (if there is no other above, like generated by Pretty Printer for forms.) See additional description below.
7. All comments inside implementation of forms, methods and similar coding blocks are ignored, except starting with two characters: *". They can be placed inside block, but refer not to the following statement, but block as general (see point 3.1.4).
8. There should be at least one blank line after program comments and the following comments (for instance assigned to form or program event).
9. It is possible to place special predefined tags (variables) at the beginning of comment. They start with @ (at).  The list of predefined tags is below. Tags starts different parts of comment and can be used to generate a special output format (for instance use different colors or font for each comment's part).
10. Comments can include HTML formatting tags. The typical is
    for line break. If you need then to write characters: <, >, &, | or ~, you need to enter:
    <           <
    >           >
    &          &
    |           ¦
    ~           ˜
    It is controlled by parameter on selection screen of the ZICDOC program.

2.1.2 Special tags in comments

Comments can contain variables (tags) starting with character @. They can be any single word. There are several predefined (assumed to be used) but other are treated in the same way - a special formatting cab be applied in output file.

List of examples:

• @Info - description of the object. It is default tag for comment, so it is assigned also if no tag has been written at the beginning of the comment. The word Info is not outputted to HTML file.
• @Author - author of the code
• @Date - date of creation
• @Change - change details

The following tags are treated in different way. The generator use the word following the tag as its special parameter (like in: * @Param I_MATNR Material number). Parameters can be issued with different formatting options (font). Only the following predefined variables can have parametrs (it is hard-coded):

• @Param - parameter of form, method
• @Using - parameter of form
• @Change, @Changing - parameter of form
• @Import, @Importing - import parameter
• @Export, @Exporting - export parameter
• @Return, @Returning - return parameter
• @Receiving - parameter of method
• @Tables - table parameter
• @Throws, @Exception, @Raising - exception generated by code

2.1.3 Program comments

At the beginning of each main program or include it is possible to write comment describing this unit. This comment is recognized by beginning characters: *&. It is not required, that all lines of this part begins with these 2 characters. It is enough, that the first line begins with them. All following lines can begin with single character *.

Program comment can start in any line of code, even at the end of program. I suggest to enter it at the beginning, because Pretty Printer generates form's header comments beginning wit *&, so it can lead to unexpected results. Program comment ends with the firs blank line or statement (just no-comment). Example:

*&---------------------------------------------------------------------*
*& Report  ZICDOC_TEST1
*&
*&---------------------------------------------------------------------*
*& @Author Ireneusz Cwir
*& @Date 18.01.2008
*& @Info Program for testing documentation generation by ZICDOC
*&---------------------------------------------------------------------*
* This comment, although doesn't begin with '*&' belong to program's
* description part. It is because there is no empty line between
* above section and this section.
It will start in new line -
* thanks to HTML tag: <br>
* Line with horizontal separator is ignored.
*
* This comment also belongs to above section, because line above
* starts with '*', so it is no really blank line.

* This doesn't belong to previous section, because there is really
* empty line above.

2.1.4  Code units comments

Comments for forms, list events and other similar code units are placed before the unit. The last continuous section of comment (without blank line) before unit is assigned to that unit.

Comments can contain special tags using for marking special sections of comments (like author, date, parameters - see point 3.1.2).

If you want to output comment from inside form or method, you must use comment starting with*".

3 Output file sections

Output HTML file can contain different sections. Selection screen parameters control this. Sections are describe below.

3.1 Hierarchy of programs and includes

Section lists all includes used in the program. They are printed as subnodes of the analyzed program. This section contains also macros called from the program. If source code of include has been available for analysis and detailed section should be generated, nodes are created as links to detailed descriptions of each include.

3.2 Database tables

Section lists database tables used in the program (covers includes). The following information is displayed for each table:

• Table name
• Access mode:
  T - declaration with TABLES statement
  S - select
  U - update
  I - insert
  M - modify (update or insert)
  D - delete
• Table title - from dictionary

3.3 Programs and includes summary

This section contains the following information for each program (include):

• Program name
• Program title - from attributes screen of a program
• Program description - from program comments (see point 3.1.3)
• List of events, forms and other code units defined in the program (include)

3.4 Class components

Section contains more detailed information about classes defined and implemented in analyzed program:

• Class name and its declaration
• Base class
• Attributes and methods with comments - based on class definition. Comments are displayed also from method implementation.

3.5 Non-class code units

Section contains more detailed information about code units in each program (include):

• Type of code unit (list event, form, function)
• Name of the unit
• Parameters of the unit
• Database tables affected by the unit (with access mode: reads, updates - see point 4.2)
• Unit description - comments before unit code

3.6 Code units calls hierarchy

The section contains hierarchy of calls of forms, function modules and other code units. It is intended for documenting reports. Then, list events are roots of calls. Other program types have not been tested. For instance, it does not list calls made from class methods.

ZICDOC does not recognize methods calls if short version are used.