parameters: (doc)
return_statement: return param_str, ret
docstring: Takes a function and returns the params and return value as a tuple.
      This is nothing more than a docstring parser.
  
      TODO docstrings like utime(path, (atime, mtime)) and a(b [, b]) -> None
      TODO docstrings like 'tuple of integers'
docstring_summary: Takes a function and returns the params and return value as a tuple.
      This is nothing more than a docstring parser.
docstring_tokens: Takes a function and returns the params and return value as a tuple . This is nothing more than a docstring parser .
function: def _parse_function_doc(doc):
      """
      Takes a function and returns the params and return value as a tuple.
      This is nothing more than a docstring parser.
  
      TODO docstrings like utime(path, (atime, mtime)) and a(b [, b]) -> None
      TODO docstrings like 'tuple of integers'
      """
      doc = force_unicode(doc)
      # parse round parentheses: def func(a, (b,c))
      try:
          count = 0
          start = doc.index('(')
          for i, s in enumerate(doc[start:]):
              if s == '(':
                  count += 1
              elif s == ')':
                  count -= 1
              if count == 0:
                  end = start + i
                  break
          param_str = doc[start + 1:end]
      except (ValueError, UnboundLocalError):
          # ValueError for doc.index
          # UnboundLocalError for undefined end in last line
          debug.dbg('no brackets found - no param')
          end = 0
          param_str = u''
      else:
          # remove square brackets, that show an optional param ( = None)
          def change_options(m):
              args = m.group(1).split(',')
              for i, a in enumerate(args):
                  if a and '=' not in a:
                      args[i] += '=None'
              return ','.join(args)
  
          while True:
              param_str, changes = re.subn(r' ?\[([^\[\]]+)\]',
                                           change_options, param_str)
              if changes == 0:
                  break
      param_str = param_str.replace('-', '_')  # see: isinstance.__doc__
  
      # parse return value
      r = re.search(u'-[>-]* ', doc[end:end + 7])
      if r is None:
          ret = u''
      else:
          index = end + r.end()
          # get result type, which can contain newlines
          pattern = re.compile(r'(,\n|[^\n-])+')
          ret_str = pattern.match(doc, index).group(0).strip()
          # New object -> object()
          ret_str = re.sub(r'[nN]ew (.*)', r'\1()', ret_str)
  
          ret = docstr_defaults.get(ret_str, ret_str)
  
      return param_str, ret
function_tokens: def _parse_function_doc ( doc ) : doc = force_unicode ( doc ) # parse round parentheses: def func(a, (b,c)) try : count = 0 start = doc . index ( '(' ) for i , s in enumerate ( doc [ start : ] ) : if s == '(' : count += 1 elif s == ')' : count -= 1 if count == 0 : end = start + i break param_str = doc [ start + 1 : end ] except ( ValueError , UnboundLocalError ) : # ValueError for doc.index # UnboundLocalError for undefined end in last line debug . dbg ( 'no brackets found - no param' ) end = 0 param_str = u'' else : # remove square brackets, that show an optional param ( = None) def change_options ( m ) : args = m . group ( 1 ) . split ( ',' ) for i , a in enumerate ( args ) : if a and '=' not in a : args [ i ] += '=None' return ',' . join ( args ) while True : param_str , changes = re . subn ( r' ?\[([^\[\]]+)\]' , change_options , param_str ) if changes == 0 : break param_str = param_str . replace ( '-' , '_' ) # see: isinstance.__doc__ # parse return value r = re . search ( u'-[>-]* ' , doc [ end : end + 7 ] ) if r is None : ret = u'' else : index = end + r . end ( ) # get result type, which can contain newlines pattern = re . compile ( r'(,\n|[^\n-])+' ) ret_str = pattern . match ( doc , index ) . group ( 0 ) . strip ( ) # New object -> object() ret_str = re . sub ( r'[nN]ew (.*)' , r'\1()' , ret_str ) ret = docstr_defaults . get ( ret_str , ret_str ) return param_str , ret