View of /netsukuku/src/HACKING

    1 *
    2 **  General suggestions
    3 *
    4 
    5 - Use the following tags based programs:
    6 
    7   Vim    : http://www.vim.org/
    8   ctags  : http://ctags.sourceforge.net
    9   Cscope : http://cscope.sourceforge.net
   10   |{WoC}|: http://www.freaknet.org/alpt/src/utils/woc/readme
   11 
   12 
   13 - If you see a word surrounded by semicolon, jump on it (you need cscope).
   14   Example:
   15    ...
   16    *
   17    * This structure is used in :map_node:.
   18    *
   19    ...
   20 
   21   If you see something like {-this-}, that's a WoC tag. You can jump on it, but
   22   you need a {-WoC-} client: http://www.freaknet.org/alpt/src/utils/woc/readme
   23 
   24 - Use TODO.h, CITE.h . They are useful to avoid the pollution of the comment
   25   space of the sources.
   26 
   27 - See http://idiki.dyne.org/wiki/HLL_overview
   28 
   29 - Read /usr/src/linux/Documentation/CodingStyle
   30 
   31 
   32 *
   33 ** Functions names
   34 *
   35 
   36 In the name of exported functions defined in foo.c use the prefix `foo_' or
   37 its abbrevation. For example,
   38 
   39   int foo_bar(int gh) {  };
   40 
   41 In the first part of the function, put what the function is operating on, then
   42 in the last part put the action performed by it.
   43 For example:
   44 
   45   RIGHT:  void map_node_del(map_node *node);
   46 
   47   WRONG:  void map_del_node()
   48   WRONG:  void del_map_node()
   49 
   50 Note: for local/private functions you can omit the prefix.
   51 
   52 *
   53 ** Pack syntax              |{pack-syntax}|
   54 *
   55 
   56 The following syntax is used to describe a pack of a complex structure:
   57 
   58   { TOKEN }^NUMBER, { TOKEN }^NUMBER, ...
   59 
   60 Where,
   61 
   62   TOKEN is anything that can be read and written in memory, for example,
   63   TOKEN can be one of the following:
   64 
   65     - an array
   66     - a variable
   67     - a type of a variable
   68     - a structure (better if packed)
   69     - another { TOKEN }^NUMBER group
   70 
   71   NUMBER is a natural number, indicating the number of repetitions of the
   72   previous { TOKEN }. When it is 1, it can be omitted.
   73   For example:
   74 
   75     { int }^3  is the same of  { int }, { int }, { int }
   76     { int }    is the same of  { int }^1
   77 
   78 This syntax is useful to describe how the pack space is logically divided.
   79 For example, suppose we want to pack the following struct:
   80 
   81   struct astruct {
   82     int o;
   83     char mi[7];
   84   } mystruct[19];
   85 
   86 the pack can be described as:
   87 
   88   { { int }, { char }^7 }^19
   89 
   90 (In this case it's better to use {-packed-attr-})
   91 
   92 For real world examples, see {-pack-syntax:"r-}
   93 
   94 
   95 *
   96 ** Self syntax
   97 *
   98 
   99 The word `self', when used in a comment placed inside a structure
  100 definition, refers to the same structure. Ex:
  101 
  102   struct foo
  103   {
  104     /*
  105      * self.baz is a friend of self.bar
  106      */
  107 
  108     int bar;
  109     int baz;
  110   }
  111 
  112 Suppose we have a nested structure definition, then we'll use the ^^ symbol to
  113 refer to the top structure. Ex:
  114 
  115   struct map
  116   {
  117     struct node
  118     {
  119       /*
  120        * Coordinates relative to this ^^map
  121        */
  122       int xyz;
  123     }
  124   }
  125 
  126 The ^^ symbol can be also used to indicate the upper structures. Ex:
  127 
  128   struct map
  129   {
  130     struct group
  131     {
  132       /*
  133        * Distance from the start of the  self^^map  map
  134        */
  135       int group_distance;
  136 
  137       struct node
  138       {
  139         /*
  140          * Distance from the start of the
  141          * self^^group^^map  map
  142          */
  143         /*
  144          * Distance from the start of the ^^map
  145          */
  146         int node_distance;
  147       }
  148     }
  149   }
  150 
  151 *
  152 *** Star syntax
  153 *
  154 
  155 By writing:
  156   array[*]
  157 we mean:
  158   forall members of array[*]