Discussed a technique for better mail address resolution.

git-svn-id: https://hudson.dev.java.net/svn/hudson/trunk/hudson/main@27624 71c3de6d-444a-0410-be80-ed276b4c234a

core/src/main/java/hudson/tasks/MailAddressResolver.java

@@ -29,6 +29,8 @@ import hudson.ExtensionListView;
 import hudson.ExtensionPoint;
 import hudson.model.Hudson;
 import hudson.model.User;
+import hudson.model.UserProperty;
+import hudson.scm.SCM;
 
 import java.util.List;
 import java.util.logging.Logger;
@@ -49,6 +51,17 @@ import java.util.regex.Pattern;
  * }
  * </pre>
  *
+ * <h2>Techniques</h2>
+ * <p>
+ * User identity in Hudson is global, and not specific to a particular job. As a result, mail address resolution
+ * only receives {@link User}, which by itself doesn't really have that much information in it.
+ *
+ * <p>
+ * So the common technique for a mail address resolution is to define your own {@link UserProperty} types and
+ * add it to {@link User} objects where more context is available. For example, an {@link SCM} implementation
+ * can have a lot more information about a particular user during a check out, so that would be a good place
+ * to capture information as {@link UserProperty}, which then later used by a {@link MailAddressResolver}. 
+ *
  * @author Kohsuke Kawaguchi
  * @since 1.192
  */