From 6f91398ce9baccd659d81e4fd6f64674716b092e Mon Sep 17 00:00:00 2001
From: Christophe Matthieu <chm@openerp.com>
Date: Wed, 23 Jan 2013 14:47:51 +0100
Subject: [PATCH] [IMP] mail_alias: add documentation

bzr revid: chm@openerp.com-20130123134751-ka74ff0guzsjod1c
---
 addons/mail/doc/mail_alias.rst | 37 ++++++++++++++++++++++++++++++++++
 addons/mail/mail_alias.py      |  6 ++++--
 2 files changed, 41 insertions(+), 2 deletions(-)
 create mode 100644 addons/mail/doc/mail_alias.rst

diff --git a/addons/mail/doc/mail_alias.rst b/addons/mail/doc/mail_alias.rst
new file mode 100644
index 00000000000..fa5a2fe0fda
--- /dev/null
+++ b/addons/mail/doc/mail_alias.rst
@@ -0,0 +1,37 @@
+.. _mail_alias:
+
+mail.alias
+============
+
+Models
++++++++
+
+``mail.alias`` is a class for mapping of an email address with a given OpenERP Document model. It is used by OpenERP's mail gateway when processing incoming emails sent to the system. If the recipient address (To) of the message matches a Mail Alias, the message will be either processed following the rules of that alias. If the message is a reply it will be attached to the existing discussion on the corresponding record, otherwise a new record of the corresponding model will be created.
+This is meant to be used in combination with a catch-all email configuration on the company's mail server, so that as soon as a new mail.alias is created, it becomes immediately usable and OpenERP will accept email for it.
+
+.. versionchanged:: 7.1
+
+Some Fields
++++++++++++
+
+ - ``alias_name`` : 
+      The name of the email alias, e.g. 'jobs'
+ - ``alias_model_id`` : 
+      The model (OpenERP Document Kind) to which this alias corresponds. Any incoming email that does not reply to an existing record will cause the creation of a new record of this model (e.g. a Project Task)
+ - ``alias_defaults`` : 
+      A Python dictionary that will be evaluated to provide default values when creating new records for this alias.
+ - ``alias_domain`` : 
+
+Methods
++++++++
+
+ - ``name_get`` :
+      Return the mail alias display alias_name, inclusing the implicit mail catchall domain from config.
+      e.g. `jobs@openerp.my.openerp.com` or `sales@openerp.my.openerp.com`
+ - ``create_unique_alias`` :
+      Creates an email.alias record according to the values provided in ``vals``, with 2 alterations: the ``alias_name`` value may be suffixed in order to make it unique, and the ``alias_model_id`` value will set to the model ID of the ``model_name`` value, if provided, 
+ - ``get_alias`` :
+      Return the mail alias for a document (or the default mail alias of the model).
+      Arguments:
+         model (model OpenERP)
+         alias_defaults (A Python dictionary to provide default values when creating new records for this alias.)
\ No newline at end of file
diff --git a/addons/mail/mail_alias.py b/addons/mail/mail_alias.py
index 0784303d886..f7cf115be55 100644
--- a/addons/mail/mail_alias.py
+++ b/addons/mail/mail_alias.py
@@ -199,9 +199,11 @@ class mail_alias(osv.Model):
         return self.create(cr, uid, vals, context=context)
 
     def get_alias(self, cr, uid, model, alias_defaults={}, context=None):
-        """Return the mail alias for a document
+        """Return the mail alias for a document (or the default mail alias of the model)
         This method is used by the web client (method web.view.insert_alias)
-        Arguments: model and content of alias_defaults column
+        Arguments:
+            model (model OpenERP)
+            alias_defaults (A Python dictionary to provide default values when creating new records for this alias.)
         """
         model_id = self.pool.get('ir.model').search(cr, uid, [('model', '=', model)], context=context)[0]