Help a fellow developer integrate with your great module properly -- and write documentation

Hi,

I have just spent a _lot_ of hours while integrating FriendList with Rules. Now, I have two issues:

1) I am not sure I did things right
2) I feel the compelling _need_ write documentation about it. I am not a particularly good programmer, but I can write documentation. I can only do that once I've understood exactly what is going on.

Rather than just asking "is this OK?", I'd like to fully understand what's going on so that I can actually write a fantastic tutorial about it. As you will see from my questions, my understanding of this is still quite foggy.

So, you will see the code at the end of my post. Now, questions:

* What is an "identifiable" data type exactly? If you look at my code below, you will see that I defined the data type "relation_status" as identifiable. This means that there is no need for a form for it... right?

* What is the difference between configuration options and parameters , really?
The official documentation doesn't seem to match reality about it. I am immensely confused! Please allow me to tell you what I understood after a lot of trial&error, reading Rules' source code, and a bit of intuition.
From my understanding, "arguments" only really make sense when, while executing a comparison, the admin needs to pick one of the arguments passed from the event. That's what I did friendlist_rules_rules_condition_info():

 'rules_condition_relation_status_compare' => array(
      'label' => t('Compare with a status.'),
      'arguments' => array(

        'relation_status' => array(
          'label' => t('Relation status'),
          'type' => 'relation_status',
          'description' => 'The relation to compare'
        ),

      ),
      'help' => 'TRUE is returned if the relation status equals the string in the input box',
      'module' => 'Friendlist Rules',
    ),

I basically want the admin to pick amongst one of the two statuses available from the event. Note that there's a form attached as well:

/**
 * Action drupal message configuration form.
 */
function rules_condition_relation_status_compare_form($settings, &$form) {
  $settings += array('status_param' => '', );

  $options=array();
    $status_data=friendlist_api_status_data();
    foreach($status_data as $key => $v){
      $options[$key]="$key -- ".t($v['description']);
    }


  $form['settings']['status_param'] = array(
    '#type' => 'select',
    '#options' => $options,
    '#title' => t('Status'),
    '#default_value' => $settings['status_param'],
    '#description' => t('The status to compare it with'),
  );
}

This will make sure that... there's something to compare the status with. And that's taken from a list of possible states. Now, since the status is identifiable, it doesn't need a form for itself. But...

* What's the use of having un-identifiable fields as arguments, if they should effectively be settings? This questions is important... also because sometimes if I tried to add some un-identifiable fields to an action, Rules simply made it unavailable!
If you change friendlist_rules_rules_action_info() so that it has, in rules_action_friendlist_add():

    'rules_action_friendlist_add' => array(
      'label' => t('Create a relationship between users'),
      'eval input' => array(
        'user1_param',
        'user2_param',
        'rtid_param',
        'message_param'
      ),

      // ADDED TO TEST IF THE RULE IS STILL THERE
      'arguments' => array(
        'something' => array(
          'label' => t('Requester user ID'),
          'type' => 'integer',
          'description' => 'The requester of the friendlist action'
        ),
      ),

      'help' => 'Create a relationship between users',
      'module' => 'Friendlist Rules',
    ),

The action is no longer available. My only reason for that is that the event doesn't have any "integer" values, and therefore will not consider that action as a possible one for the event. Is that right?

So... having an answer to these questions would be _grand_. Please have a look at the code below, to see if I did anything silly or if I did things "Rules-way".

Thank you!

Merc.

P.S.
I was going to attach the code... however, it makes more sense to put a link to my CVS:

http://cvs.drupal.org/viewvc.py/drupal/contributions/modules/friendlist/...