Add consistency to e-commerce hooks namespaces

I have just spent quite a number of hours trying to document all the hooks and where they are called and what arguments they are called with. I would agree with you that they don't appear to be consistent and it made my head spin quite a number of times. Unfortunately, time is not something that I have enough of these days but I would be interested in helping out if there is the community support to do this.

I know that Gordon has spent oodles of his own unpaid time on this project so I don't want this to appear to slam his efforts in any way. I have been involved on and off in this project for awhile now- mostly off.

But I also know if the API is easily understood, development efforts by those new to the project would increase tremendously.

Here is one that I had real trouble trying to understand: (I added my morsels of knowledge to the code)

ec_product_invoke_productapi:
Here are the $op values that I found:
* adjust_price - allow prices to be adjusted
* cart_remove_item - to empty cart
* ec_checkout_add_complete -
* ec_checkout_validate_term - allows modules to invalidate the cart contents
* delete - to delete product from $txn
* insert - to insert product from $txn
* transaction - to update transactions
* txn_allocation - setup allocations per product
* txn_workflow
* validate - ensure a product is valid
* update - change something about a product

So here are my observations:
- they appear to affect products used in the currently loaded transaction
- the actual $op values seem to be arbitrary- whatever is needed - during development I can understand this but at some point this should be limited
- this function is really a wrapper function to call further functions which, imho, makes development alot harder
- Drupal has an api that seems to be easily extended but in the ec project, it doesn't seem to work well for noobs like myself

Here is a confusing hook:
hook_feature_ec_checkout_add_complete()
This is used in one module currently: ec_availabilty
so the hook becomes: ec_availability_ec_checkout_add_complete
which we can tell that this function is in ec_availability and is a hook called by ec_checkout_add_complete

I found the following references to hooks in ec HEAD:

hook_alloc_allocation()
hook_allocation_info()
hook_alloc_get_currency()
hook_alloc_get_payment_data()
hook_alloc_get_payment_form()
hook_alloc_get_payment_type()
hook_alloc_get_total()
hook_alloc_load()
hook_alloc_set_payment_data()
hook_cart_add_item()
hook_customer_get_address()
hook_customer_get_by_email()
hook_customer_get_by_uid()
hook_customer_get_email()
hook_customer_get_id()
hook_customer_get_info()
hook_customer_get_name()
hook_customer_get_uid()
hook_customer_info()
hook_customer_links()
hook_customer_search()
hook_ec_perm()
hook_ec_receipt_post_save()
hook_ec_receipt_status()
hook_ec_search()
hook_ec_search_format_header()
hook_ec_search_format_row()
hook_ec_search_init()
hook_ec_transaction_post()
hook_ec_transaction_pre()
hook_ec_txn_allocation()
hook_ec_txn_workflow()
hook_ec_widgets()
hook_feature_attributes()
hook_feature_delete()
hook_feature_ec_checkout_add_complete()
hook_feature_ec_checkout_validate_item()
hook_feature_info()
hook_feature_insert()
hook_feature_load()
hook_feature_update()
hook_mail_reset()
hook_mail_types()
hook_product_form_alter()
hook_product_types()
hook_product_types()
hook_receipt_info()
hook_receipt_load()
hook_receipt_payment_form()
hook_receipt_payment_url()
hook_receipt_process_payment()
hook_receipt_save()
hook_refund()
hook_requirements()
hook_rules_condition_info()
hook_rules_event_info()

And here were the APIs that I found that are ec APIs
hook_transactionapi()
hook_checkoutapi()
hook_ec_transactionapi().
hook_invoiceapi().

Maybe we should have:
hook_featureapi ?
hook_receiptapi ?

ec_availability_ec_checkout_add_complete
- should this be "ec_availability_checkoutapi("add_complete)" instead?

I would like to know what Gordon thinks about all this.

I am just rambling on now ... lets talk more about this.... and v4 is in RC now so this would probably d7/ecv5 unless Gordon is open to changes.