I can't really believe that this list is empty...

I quickly tried to make sense of Keys API for #536050: Keys API integration (Mollom), but could not find ANY documentation or code example or whatever. No handbook pages. Not even a list of "modules using Keys API". Not even criticism. :P

Asking for two key deliverables here:

1) keys.api.php - following Drupal 7 standards, all module hooks should be documented here. May also contain/use a @file or @defgroup section to document implementor usage + example snippets. Much like sub-systems in D7 core are documented. Examples:
http://api.drupal.org/api/group/ajax/7
http://api.drupal.org/api/group/form_api/7
http://api.drupal.org/api/function/drupal_process_states/7

2) Depending on the output of 1), a separate handbook page might make sense. If keys.api.php isn't suitable to sufficiently document this API, or when it changes too often or many people may want to add too many things, then a handbook page would be a better way for documentation. In general though, .api.php is preferred, as it's also maps to the module version/branch contained and shipped with.

I hope I'm not asking for too much. Let me repeat that I would have already coded ahead if it was totally obvious.

CommentFileSizeAuthor
#3 keys.api_.php_.diff1.06 KBgreenskin

Comments

sun’s picture

sun
Primary language German
Location Karlsruhe
commented
Category: bug » task

um, wrong category.

greenskin’s picture

greenskin commented
Assigned: Unassigned » greenskin

Thanks! I'll get right on it.

greenskin’s picture

greenskin commented
StatusFileSize
new keys.api_.php_.diff1.06 KB

I've attached what I came up with for keys.api.php. I'm not very good with doxygen stuff so feel free to make any improvements if needed. Also, let me know if more explaining needs to be done or if it is not clear enough explanations.

As for a handbook page, I would like to set something up but I'm a little intimidated by it. I'm not sure of where to start it, categorize it and such. Mostly intimidated by the Do NOT create test pages. :P

I'd like to better explain how to use some of the functions provided by Keys and thought a handbook page would be perfect.

sun’s picture

sun
Primary language German
Location Karlsruhe
commented 
+++ (current document)
@@ -0,0 +1,35 @@
+ * as the service a key would be used for. For instance Google Maps is a
+ * service that keys can be assigned to.

Good starting point. One of the first questions is: What if my (single) service requires two keys to operate?

I'd recommend to have a look at includes/form.inc and includes/ajax.inc - two great examples of @defgroup documentation - in Drupal 7 core (CVS HEAD). Oh, I also forgot to mention that most core sub-system hooks are documented in modules/system/system.api.php in D7, also a good read.

The general rule of thumb for documenting APIs is:

- High-level API documentation, such as writing a simple form workflow or AJAX operation, belongs into @defgroup, also providing general overview about the API and its features, common hiccups, etc. Implementors can and should start from here.

- PHPDoc Doxygen function headers for the hooks that a module exposes should obviously explain the arguments passed to the hook and be elaborate about the expected return value(s). Any details that implementors should know when implementing the API should be stated here.

- Inline comments should contain docs for the API authors, not implementors.

Powered by Dreditor.

sun’s picture

sun
Primary language German
Location Karlsruhe
commented

Also, I'd highly recommend a keys.api.php file shipped with the module instead of a handbook page. But of course, that's your decision.

greenskin’s picture

greenskin commented

I will have a keys.api.php file to ship with the module. I was going to use a handbook page to further explain using the API.

sun’s picture

sun
Primary language German
Location Karlsruhe
commented

Note that I'm similarly working on implementor documentation for Mollom's API over in #775444: API implementor documentation

I'm totally not saying that this serves as best practice example or whatnot, but you might get an additional idea of how such a patch could look like.

greenskin’s picture

greenskin commented

What if my (single) service requires two keys to operate?

Originally the term service was chosen with the understanding that a service would only request a single key and was labeled 'service' as it best described what the key was used for. Perhaps the term 'service' should be changed. But back on point, if you need to request multiple keys you should request them by a unique service. The keys service is simply used as a unique identifier to the type of key needed. The service can be anything, for instance 'google_maps' or 'google_search'. You can then load the service key you need based on the service identifier. Basically when a key is requested, only one will be returned and as such the closest one matching the rule will be returned. If you need multiple then define multiple services such as 'example_service1' and 'example_service2' and call them separately.