Extend getfields function to cope with actions, metadata

We are trying to build more information / flexibility into the getfields code documentation - including mandatory fields, defaults, ways in which fields can be used, which functions fields apply to.

The expectation is that the api documentation will be largely generated from the output of the getfields function. In addition, getfields output is used for field validation - currently only dates but eventually others too. It can also be used for generating UI interfaces to the API - e.g. specifiying what fields to include in an token to make it transportable from site to site)

First round of spec is that getfields can be altered on function

/*

• return field specification specific to get requests
  */
  function _civicrm_api3_pledge_get_spec(&$params){
  $params['next_pay_date'] = array(
  'name' => 'next_pay_date',
  'type' => 12,
  'title' => 'Pledge Made',
  'api.filter' => 0,
  'api.return' => 1,

);
}

'next_pay_date' is a field that is / can be returned but (TBC) can't be an input filter.

Here is a variant for settng mandatory fields (note that civicrm_api would enforce this).

/*

• return field specification specific to get requests
  */
  function _civicrm_api3_pledge_create_spec(&$params){

$required = array('contact_id', 'amount', 'installments','start_date');
foreach ($required as $required_field)

{ $params[$field]['api.required'] = 1; }

}

Note that this option won't support / document verify_one_mandatory for and/or fields.