Class: FunctionDoc
Documentation for a single function or method. Takes a parsed comment and provides accessors for accessing the various fields.
>>> comments = parse_comments_for_file('examples/module_closure.js')
>>> fn1 = FunctionDoc(comments[1])
>>> fn1.name
'the_first_function'
>>> fn1.doc
'The auto-naming can pick up functions defined as fields of an object,\n as is common with classes and the module pattern.'
Constructor
__init__ (self, parsed_comment)
Methods
get (self, tag_name, default='')
Return the value of a particular tag, or None if that tag doesn't exist. Use 'doc' for the comment body itself.
get_as_list (self, tag_name)
Return the value of a tag, making sure that it's a list. Absent tags are returned as an empty-list; single tags are returned as a one-element list.
The returned list is a copy, and modifications do not affect the original object.
to_dict (self)
Convert this FunctionDoc to a dictionary. In addition to CommentDoc keys, this adds:
- name: The function name
- params: A list of parameter dictionaries
- options: A list of option dictionaries
- exceptions: A list of exception dictionaries
- return_val: A dictionary describing the return type, as per ParamDoc
- is_private: True if private
- is_constructor: True if a constructor
- member: The raw text of the member property.
to_html (self, codebase)
Convert this FunctionDoc to HTML.
to_json (self)
Return a JSON representation of the CommentDoc. Keys are as per to_dict.
Properties
doc
Return the comment body.
exceptions
Returns a list of ParamDoc objects (with empty names) of the exception tags for the function.
>>> comments = parse_comments_for_file('examples/module_closure.js')
>>> fn1 = FunctionDoc(comments[1])
>>> fn1.exceptions[0].doc
'Another exception'
>>> fn1.exceptions[1].doc
'A fake exception'
>>> fn1.exceptions[1].type
'String'
is_constructor
Return True if this function is a constructor.
is_private
Return True if this is a private function or method.
member
Return the raw text of the @member tag, a reference to a method's containing class, or None if this is a standalone function.
name
options
Return the options for this function, as a list of ParamDocs. This is a common pattern for emulating keyword arguments.
>>> comments = parse_comments_for_file('examples/module_closure.js')
>>> fn2 = FunctionDoc(comments[2])
>>> fn2.options[0].name
'foo'
>>> fn2.options[1].type
'Int'
>>> fn2.options[1].doc
'Some other option'
params
Returns a ParamDoc for each parameter of the function, picking up the order from the actual parameter list.
>>> comments = parse_comments_for_file('examples/module_closure.js')
>>> fn2 = FunctionDoc(comments[2])
>>> fn2.params[0].name
'elem'
>>> fn2.params[1].type
'Function(DOM)'
>>> fn2.params[2].doc
'The Options array.'
return_val
Returns the return value of the function, as a ParamDoc with an empty name:
>>> comments = parse_comments_for_file('examples/module_closure.js')
>>> fn1 = FunctionDoc(comments[1])
>>> fn1.return_val.name
''
>>> fn1.return_val.doc
'Some value'
>>> fn1.return_val.type
'String'
>>> fn2 = FunctionDoc(comments[2]) >>> fn2.return_val.doc 'Some property of the elements.' >>> fn2.return_val.type 'Array<String>'
see
Return a list of all @see tags on the comment.
url
Return a URL for the comment, within the page.