
settings = {
  # [[modifier ]type ]arg[square brackets, white spaces, ...](,|EOL) with support
  # of prototype as argument types (not recursive).
  # 
  # Detailed expression:
  #function_args=(?:
  #                  matches () and (void) not to try to extract an argument for them
  #               ^\([ \t]*(?:void)?[ \t]*\)$
  #               |
  #                  type or modifier (e.g. "char *")
  #               (?:[a-zA-Z0-9_]+[ \t*]+
  #                   prototype start (e.g. "(*", start of (*arg))
  #                (?:\([ \t*]*)?)*
  #                the argument name itself (only capture)
  #               ([a-zA-Z0-9_.]+)
  #                  prototype end (e.g. ")", end of (*arg))
  #               (?:[ \t]*\))?
  #               possible white-spaces
  #               [ \t]*
  #                  prototype arguments: we match anything between parentheses
  #               (?:\([^)]*\))?
  #               permissive match for post-arg (e.g. array size)
  #               [^,]*
  #               , or EOL
  #               (?:,|$)
  #              )
  # note that \ are escaped, so to have a \ you need to put \\
  match_function_arguments = "(?:^\\([ \t]*(?:void)?[ \t]*\\)$|(?:[a-zA-Z0-9_]+[ \t*]+(?:\\([ \t*]*)?)*([a-zA-Z0-9_.]+)(?:[ \t]*\\))?[ \t]*(?:\\([^)]*\\))?[^,]*(?:,|$))";
  
  # global env
  global_environment = "doxygen_prefix  = \"@\";
                        write_since     = 0;";
}

doctypes = {
  gtkdoc = {
    # Forward should be before the others to match first
    struct.struct.policy    = FORWARD;
    struct.union.policy     = FORWARD;
    struct.prototype.policy = FORWARD;
    member.policy           = FORWARD;
    enumval.policy          = FORWARD;
    # usually, locals are just not documented and get in the way
    local.policy            = FORWARD;
    # usually nothing useful to document
    include.policy          = PASS;
    other.policy            = PASS;
    
    function = {
      template = "/**\n * {symbol}:\n{for arg in argument_list} * @{arg}: {cursor}\n{end} * \n * {cursor}\n{if returns} * \n * Returns: \n{end}{if write_since}{if returns} * \n{end} * Since: \n{end} */\n";
      position = BEFORE;
      policy   = KEEP;
    }
    macro = {
      template = "/**\n * {symbol}:\n{for arg in argument_list} * @{arg}: {cursor}\n{end} * \n * {cursor}\n{if returns} * \n * Returns: \n{end} */\n";
    }
    struct = {
      template = "/**\n * {symbol}:\n{for member in children} * @{member}: {cursor}\n{end} * \n * {cursor}\n */\n";
      position = BEFORE;
      policy   = KEEP;
      children = MERGE;
      matches  = member | prototype;
    }
    enum = {
      template = "/**\n * {symbol}:\n{for enumval in enumval_list} * @{enumval}: {cursor}\n{end} * \n * {cursor}\n */\n";
    }
    union = {
      template = "/**\n * {symbol}:\n{for member in children} * @{member}: {cursor}\n{end} * \n * {cursor}\n */\n";
      children = MERGE;
    }
    typedef = {
      template = "/**\n * {symbol}:\n * \n * {cursor}\n */\n";
    }
    define = {
      template = "/**\n * {symbol}:\n * \n * {cursor}\n */\n";
    }
  }

  doxygen = {
    # usually, locals are just not documented and get in the way
    local.policy = FORWARD;
    # usually nothing useful to document
    include.policy  = PASS;
    other.policy    = PASS;

    function.template = "/**\n * {doxygen_prefix}brief {cursor}\n{for a in argument_list} * {doxygen_prefix}param {a} \n{end}{if returns} * {doxygen_prefix}returns \n{end}{if write_since} * {doxygen_prefix}since \n{end} * \n * \n */\n";
    macro.template    = "/**\n * {doxygen_prefix}brief {cursor}\n{for a in argument_list} * {doxygen_prefix}param {a} \n{end}{if returns} * {doxygen_prefix}returns \n{end}{if write_since} * {doxygen_prefix}since \n{end} * \n * \n */\n";
    struct.member = {
      template = " /**< {cursor} */";
      position = AFTER;
    }
    struct = {
      template          = "/**\n * {doxygen_prefix}brief {cursor}\n * \n * \n */\n";
      auto_doc_children = True;
    }
    union.member = {
      template = " /**< {cursor} */";
      position = AFTER;
    }
    union = {
      template          = "/**\n * {doxygen_prefix}brief {cursor}\n * \n * \n */\n";
      auto_doc_children = True;
    }
    enum = {
      template          = "/**\n * {doxygen_prefix}brief {cursor}\n * \n * \n */\n";
      auto_doc_children = True;
    }
    enum.enumval = {
      template = " /**< {cursor} */";
      position = AFTER;
    }
    typedef.template  = "/**\n * {doxygen_prefix}brief {cursor}\n * \n * \n */\n";
    define.template   = "/**\n * {doxygen_prefix}brief {cursor}\n * \n * \n */\n";
  }
}

