home *** CD-ROM | disk | FTP | other *** search
/ RISC DISC 1 / RISC_DISC_1.iso / pd_share / code / desklib / Docs / HelpCommnt < prev    next >
Encoding:
Text File  |  1994-05-29  |  6.0 KB  |  175 lines
  1. DeskLib help comments
  2. =====================
  3.  
  4. Tim Browse is currently finishing off a utility program which will scan
  5. DeskLib sources and headers for comments in a specific format, from which
  6. it will compile a help database in StrongHelp or HyperView (CC WordWorks)
  7. format. This will give a proper hyperlinked help database for DeskLib,
  8. saving you from having to read through header files to try to figure stuff
  9. out.
  10.  
  11. The various blank comment blocks are given in the Docs.HelpCommnt, but here
  12. is a brief description of how they work:
  13.  
  14. The comment block is made up of 3 sections: A header which identifies the
  15. block as a help-comment, and indicates the type of object the help is on;
  16. A definition of the object (variable, typedef, class, function prototype);
  17. and a description. These are described below:
  18.  
  19. 1) The header is a single line similar to this:
  20.  
  21.    /*C**************************************************************
  22.  
  23.    The capital letter identifies the type of item, in this case, a 'C'
  24.    for "class". Other letters include "F"unction, "V"ariable, etc.
  25.  
  26.    (Note that this first line may be the start of one large comment block,
  27.    or you can place the two halves of the comment around a piece of actual
  28.    code when declaring functions or typedefs etc in headers)
  29.  
  30. 2) The object itself.
  31.    This is either a chunk of code defining a thing, or a copy of that code
  32.    You MUST use a copy if .c files, but in headers you may just place the
  33.    real definition here (but be very careful to make the comments on either
  34.    side individual comments - it is recommended that you use syntax-
  35.    colouring editors such as Zap when doing this.
  36.  
  37.    If it is a comment, this is sometimes preceeded by a greater-than symbol,
  38.    e.g:
  39.  
  40.    > void MyFunction(int blobby);
  41.  
  42.  
  43. 3) The help
  44.    This may be preceeded by a comment line of dashes.
  45.    This is made up of a set of fields which are described below. These
  46.    fields may be multi-line.
  47.    Fields that are not relevant may be omitted, or filled in with a "-"
  48.  
  49.     MACRO:
  50.        Used to give a function prototype for a #define'd macro, so that it
  51.        is clear how the macro is intended to be used. (See examples, below)
  52.  
  53.     Purpose:
  54.        This field describes what the thing does
  55.  
  56.     Inputs:
  57.        Lists the parameters to a function, and what they are for
  58.  
  59.     Outputs:
  60.       Lists the values returned by a function through parameters
  61.  
  62.     Returns:
  63.       Describes the return value of a function
  64.  
  65.     Errors:
  66.       Describes what errors/assertions the function can generate, when, and why
  67.  
  68.     Base:
  69.       The base class, or class derivation hierarchy
  70.  
  71.     Fields:
  72.       Describes fields of a structure type or class. Each field should be
  73.       listed by its name (NOT type), with a brief description
  74.  
  75.     SeeAlso:
  76.       This field has semicolon-separated names of other things on which help
  77.       can be found - these make up the hyper-links to other help fields, so
  78.       please use these liberally to provide useful cross-references
  79.  
  80.  
  81.  
  82. EXAMPLE 1:
  83.   Here is an example of a small header and related .c file.
  84.  
  85.  
  86. --- Bob.h ---
  87.  
  88. /*T*************************************************************************/
  89.  
  90. typedef struct
  91. {
  92.    int  a, b;
  93.    char c;
  94. } BobStruct;
  95.  
  96. /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  97.  
  98.   Purpose:  For Bob; To contain two ints and a char
  99.   Fields:   a - An int which is not used for anything
  100.             b - An int which is used to pad the space between a and c
  101.             c - A char just to prove that I don't discriminate against types
  102.   SeeAlso:  Bob_GetAnInteger
  103.  
  104. ****************************************************************************/
  105.  
  106.  
  107. /*F*************************************************************************/
  108.  
  109. extern int Bob_GetAnInteger(int whichone, int ignored);
  110.  
  111. /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  112.  
  113.   Purpose:  Returns the integer passed to it
  114.   Inputs:   whichone - The integer you want returned
  115.             ignored  - Another integer which is ignored completely
  116.   Outputs:  -
  117.   Returns:  The integer which was passed in in 'whichone'
  118.   Errors:   -
  119.   SeeAlso:  Bob_GetAnIntegerPlusOne; BobStruct
  120.  
  121. ****************************************************************************/
  122.  
  123.  
  124. --- Bob.c ---
  125.  
  126. extern int Bob_GetAnInteger(int whichone)
  127. {
  128.    return(whichone);
  129. }
  130.  
  131.  
  132.  
  133.  
  134. EXAMPLE 2: Macros and keywords:
  135.  
  136. /*M*************************************************************************/
  137.  
  138.   #define Coord_RectsIntersect(r1, r2) (Coord_RectsOverlap(r1, r2) && \
  139.                                        !Coord_RectContained(r1, r2) && \
  140.                                        !Coord_RectContained(r2, r1))
  141.  
  142. /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  143.  
  144.   MACRO:    BOOL Coord_RectsIntersect(wimp_rect *rect1, wimp_rect *rect2)
  145.  
  146.   Inputs:   rect1, rect2 - the rectangles to check for intersection
  147.   Returns:  TRUE if rectangles intersect but do not contain each other;
  148.             FALSE otherwise.
  149.   Purpose:  Tests if two rectangles intersect each other, but wil return
  150.             failure if either rectangle wholly contains the other one.
  151.             This is different to the behaviour of Coord_RectsOverlap.
  152.   SeeAlso:  Coord_RectsOverlap
  153.  
  154. ****************************************************************************/
  155.  
  156. /*K**************************************************************************
  157.  
  158. > Coordinate conversion.
  159.  
  160.   Screen <---> Work Area conversion routines.
  161.   NOTE:
  162.     "Screen Coordinates" refers to OS coordinates, with the bottom
  163.       left corner of the screen being placed at the screen origin, (0,0)
  164.     "Work Area Coordinates" refers to Coordinates within the Window's
  165.       work area, where the (0,0) origin is at the TOP left of the work area
  166.  
  167.   Some of these routines have been defined as macros because they are
  168.   very elementary, and are common, so efficiency will be improved by
  169.   removing the function call overhead.
  170.  
  171.   To keep compatibility with the syntax of Acorn's coords_ calls, these
  172.   macros still accept a pointer to a convert_block.
  173.  
  174. ****************************************************************************/
  175.