markdown/additional/design/conventions.md

   1 # Documentation conventions
   2
   3 Due to the potential for exponential growth, several abbreviating
   4 conventions will be used throughout this documentation. These
   5 conventions have grown primarily from extremely in-depth discussions of
   6 the architecture in IRC. This has verified the safety of these
   7 conventions, if used properly. There are no known namespace conflicts as
   8 long as context is rigorously observed.
   9
  10 ## Object classes
  11
  12 Since everything starts with Gst, we will generally refer to objects by
  13 the shorter name, i.e. `Element` or `Pad`. These names will always have
  14 their first letter capitalized.
  15
  16 ## Function names
  17
  18 Within the context of a given object, functions defined in that object’s
  19 header and/or source file will have their object-specific prefix
  20 stripped. For instance, `gst_element_add_pad()` would be referred to as
  21 simply `*add_pad()`. Note that the trailing parentheses should always be
  22 present, but sometimes may not be. A prefixing underscore (*) will
  23 always tell you it’s a function, however, regardless of the presence or
  24 absence of the trailing parentheses.
  25
  26 ## defines and enums
  27
  28 Values and macros defined as enums and preprocessor macros will be
  29 referred to in all capitals, as per their definition. This includes
  30 object flags and element states, as well as general enums. Examples are
  31 the states `NULL`, `READY`, `PLAYING`, and `PAUSED`; the element flags
  32 `LOCKED_STATE`, and state return values `SUCCESS`, `FAILURE`, and `ASYNC`.
  33 Where there is a prefix, as in the element flags, it is usually dropped
  34 and implied. Note however that element flags should be cross-checked
  35 with the header, as there are currently two conventions in use: with and
  36 without `*FLAGS*` in the middle.
  37
  38 ## Drawing conventions
  39
  40 When drawing pictures the following conventions apply:
  41
  42 ### objects
  43
  44 Objects are drawn with a box like:
  45
  46 ```
  47 +------+
  48 |      |
  49 +------+
  50 ```
  51
  52 ### pointers
  53
  54 a pointer to an object.
  55
  56 ```
  57      +-----+
  58 *--->|     |
  59      +-----+
  60 ```
  61
  62 an invalid pointer, this is a pointer that should not be used.
  63
  64 ```
  65 *-//->
  66 ```
  67
  68 ### elements
  69
  70 ```
  71  +----------+
  72  | name     |
  73 sink       src
  74  +----------+
  75 ```
  76
  77 ### pad links
  78
  79 ```
  80 -----+    +---
  81      |    |
  82     src--sink
  83 -----+    +---
  84 ```