E-mail
Moving toward defining standard structure and format for API docs. Ideal-world req's are:
- Doc can be used/understood by both techie and non-techie folks
- Doc can be browsed/displayed w/in Confluence space
- Doc is embedded in, or linked to/from the source code (to ensure it is maintained/kept in-synch with codebase)
Key issue...what is best encoding format for this. Drupal/CS use Doxygen comment blocks inline - http://www.stack.nl/~dimitri/doxygen/docblocks.html . Need to think though how we could integrate Doxygen HTML output with Confluence ??
Doc should include the following content elements
Name
- For now, the PHP function name. Per Drupal/PEAR coding standards, function (and API?) names are lower case with underscore separators and prefixed with module ('crm_').
Description
- Verbose description of what it does.
Parameters
- Listing of parameters. Include required/optional, default, and datatype for each.
- Reference/link to business objects when applicable to define set of param vars.
Returns
- Listing of return values. Including datatype for each. Explanation as needed.
- Reference/link to business objects when applicable to define set of return vars.
Usage Example
Related APIs and Topics
- Optional listing with links
API DOC EXAMPLE
crm_get_individal_id
Description
Allows external systems to get a contact ID for an individual (person) by matching on name and/or email fields. Returns contact ID if a unique match, returns NULL if no unique match.
Parameters
optional |
(no default) |
string |
|
$first_name |
optional |
(no default) |
string |
$middle_name |
optional |
(no default) |
string |
$last_name |
optional |
(no default |
string |
NOTE: At least one of the params above is required.
Returns
contact_id |
int |
positive int = unique match, NULL = no unique match |
Usage Example
crm_get_individual_id($email)
3 Comments
Hide/Show CommentsJan 14, 2005
Michal Mach
When we agree on final format for API documentaion, make sure we use Confluence template.
Jan 14, 2005
David Geilhufe
I think that "crm_" as the module prefix for api calls would be better as "npocrm_"
I just more clearly states the space we occupy. It also allows us to build things like a fundraising module with "npofund_" as its prefix.
Yea, I am a little focused on the details.
Jan 15, 2005
Neil Drumm
Drupal standards for function names are:
"Functions should be named using lower caps and words should be separated with an underscore. Functions should have the grouping/module name as a prefix, to avoid name collisions between modules." (http://drupal.org/node/5992)
So we should not prefix our functions with "npocrm_" unless we are writing npocrm.module, which may be a good name. I have no real preference on "crm" vs. "npocrm."
Additionally, it is also a Drupal standard to additionally prefix "private" functions with an underscore; an example is "_crm_load_stuff." I thought this was documented on Drupal.org as well, but I couldn't find any in brief looking around. Maybe I'll have to write some later