Add documentation for API typedef functions
Merge pull request #1682 from bartvde/issue-1682

better description for function typedef's params and return (r=@ahocevar)