Embedded documentation Foundation

The Source Code Editor supports you in documenting your own source code. You can specify text to be displayed as IntelliHelp tool-tip when you include XML tags within your source code. To explain how this works, have a look at a user-defined function that is included in the Xbase++ samples: CenterPos(). This function calculates the position of a window that must be displayed centered on the desktop.

01:   FUNCTION CenterPos( aSize, aRefSize ) 
02:   RETURN { Int( (aRefSize[1] - aSize[1]) / 2 ) ; 
03:          , Int( (aRefSize[2] - aSize[2]) / 2 ) } 

The function consists of three lines of code only and accepts two parameters. It returns a two element array that contains the x and y coordinates for the window position. To document this function within your code and make the embedded documentation available for the IntelliHelp system, you have to follow two rules:

An example how the XML tags can be used to document user defined functions is given below.

01:   /// <summary> 
03:   ///    Calculates a centered window position on screen from 
04:   ///    size and reference size 
05:   ///    </para> 
07:   ///    Example: 
08:   ///    </para> 
10:   ///    aRefsize := AppDesktop():currentSize() 
11:   ///    </para> 
13:   ///    aSize    := { 640, 400 } 
14:   ///    </para> 
16:   ///    aPos     := CenterPos( aSize, aRefSize ) 
18:   /// </summary> 
19:   /// <returns> 
20:   ///  aPos  { nX, nY } 
21:   /// </returns> 
22:   /// 
23:   FUNCTION CenterPos( aSize, aRefSize ) 
24:   RETURN { Int( (aRefSize[1] - aSize[1]) / 2 ) ; 
25:          , Int( (aRefSize[2] - aSize[2]) / 2 ) } 

The embedded documentation for CenterPos() includes a short description, a usage example and the function's return value. This information is extracted by the Source Code Editor and displayed as an IntelliHelp tool-tip when CenterPos() is written in the source code:

The possibility to embed documentation in source code helps a developer in re-using own functions since there is no need to look-up parameter profiles. This is especially advantageous when a project consists of a large number of PRG files.

Back

Next