[310465] descriptions for validators
diff --git a/plugins/org.eclipse.wst.validation.ui/vf2/org/eclipse/wst/validation/ui/internal/preferences/ValidationPreferencePage.java b/plugins/org.eclipse.wst.validation.ui/vf2/org/eclipse/wst/validation/ui/internal/preferences/ValidationPreferencePage.java
index 5f9683f..4ef7c3d 100644
--- a/plugins/org.eclipse.wst.validation.ui/vf2/org/eclipse/wst/validation/ui/internal/preferences/ValidationPreferencePage.java
+++ b/plugins/org.eclipse.wst.validation.ui/vf2/org/eclipse/wst/validation/ui/internal/preferences/ValidationPreferencePage.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2001, 2013 IBM Corporation and others.
+ * Copyright (c) 2001, 2017 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
@@ -17,16 +17,20 @@
 import org.eclipse.jface.dialogs.MessageDialog;
 import org.eclipse.jface.layout.GridDataFactory;
 import org.eclipse.jface.preference.PreferencePage;
+import org.eclipse.jface.viewers.ISelection;
+import org.eclipse.jface.viewers.ISelectionChangedListener;
 import org.eclipse.jface.viewers.IStructuredContentProvider;
 import org.eclipse.jface.viewers.IStructuredSelection;
 import org.eclipse.jface.viewers.ITableLabelProvider;
 import org.eclipse.jface.viewers.LabelProvider;
+import org.eclipse.jface.viewers.SelectionChangedEvent;
 import org.eclipse.jface.viewers.TableViewer;
 import org.eclipse.jface.viewers.Viewer;
 import org.eclipse.jface.viewers.ViewerSorter;
 import org.eclipse.jface.window.Window;
 import org.eclipse.swt.SWT;
 import org.eclipse.swt.custom.ScrolledComposite;
+import org.eclipse.swt.custom.StyledText;
 import org.eclipse.swt.events.FocusAdapter;
 import org.eclipse.swt.events.FocusEvent;
 import org.eclipse.swt.events.MenuAdapter;
@@ -295,6 +299,8 @@
 			addAutoSave(validatorGroup);
 			addConfirm(validatorGroup);
 
+			new Label(validatorGroup, SWT.NONE).setLayoutData(GridDataFactory.fillDefaults().span(2, 1).create());
+
 			_listLabel = new Label(validatorGroup, SWT.NONE);
 			GridData listLabelData = new GridData(GridData.FILL_HORIZONTAL);
 			listLabelData.horizontalSpan = 2;
@@ -359,6 +365,27 @@
 				}
 			});
 
+			final StyledText _descriptionText = new StyledText(validatorGroup, SWT.READ_ONLY | SWT.WRAP | SWT.BORDER);
+			_descriptionText.setBackground(validatorGroup.getBackground());
+			GridDataFactory.fillDefaults().grab(true, false).hint(SWT.DEFAULT, validatorGroup.getFont().getFontData()[0].getHeight() * 3).span(2,1).applyTo(_descriptionText);
+			_validatorList.addPostSelectionChangedListener(new ISelectionChangedListener() {
+				public void selectionChanged(SelectionChangedEvent event) {
+					ISelection selection = event.getSelection();
+					if (selection.isEmpty()) {
+						_descriptionText.setText(""); //$NON-NLS-1$
+					}
+					else {
+						String description = ((ValidatorMutable)((IStructuredSelection)selection).getFirstElement()).getDescription();
+						if (description != null) {
+							_descriptionText.setText(description);
+						}
+						else {
+							_descriptionText.setText(""); //$NON-NLS-1$
+						}
+					}
+				}
+			});
+
 			addEnableDisable(validatorGroup);
 
 			updateWidgets();
diff --git a/plugins/org.eclipse.wst.validation/vf2/org/eclipse/wst/validation/Validator.java b/plugins/org.eclipse.wst.validation/vf2/org/eclipse/wst/validation/Validator.java
index 88f5ec5..d64c29b 100644
--- a/plugins/org.eclipse.wst.validation/vf2/org/eclipse/wst/validation/Validator.java
+++ b/plugins/org.eclipse.wst.validation/vf2/org/eclipse/wst/validation/Validator.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2007, 2010 IBM Corporation and others.
+ * Copyright (c) 2007, 2017 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
@@ -507,7 +507,8 @@
 	}
 
 	public abstract String getName();
-	
+	public abstract String getDescription();
+
 	/**
 	 * Answer the project that you were enabled on. 
 	 * 
@@ -691,7 +692,11 @@
 	public String getName() {
 		return _vmd.getValidatorDisplayName();
 	}
-	
+
+	public String getDescription() {
+		return null;
+	}
+
 	public ValidatorMetaData getVmd(){
 		return _vmd;
 	}
@@ -850,6 +855,8 @@
 	
 	/** Name of the validator. */
 	private String			_name;
+	/** Longer description of the validator. */
+	private String			_description;
 	
 	/** 
 	 * We don't want to create the validator too early, as it may trigger new plug-ins to be loaded.
@@ -973,6 +980,7 @@
 
 		v._id = _id;
 		v._name = _name;
+		v._description = _description;
 		v._validatorGroupIds = _validatorGroupIds;
 		v._pendingValidationStarted = _pendingValidationStarted;
 				
@@ -1044,6 +1052,10 @@
 		return _name;
 	}
 	
+	public String getDescription() {
+		return _description;
+	}
+
 	public AbstractValidator getValidator() {
 		if (_validator == null){
 			try {
@@ -1142,7 +1154,14 @@
 			bumpChangeCountGlobal();
 		}
 	}
-	
+
+	public void setDescription(String description) {
+		if (!Misc.same(_description, description)){
+			_description = description;
+			bumpChangeCountGlobal();
+		}
+	}
+
 	@Override
 	public ValidationResult validate(IResource resource, int kind, ValOperation operation, IProgressMonitor monitor){
 		return validate(resource, kind, operation, monitor, null);
diff --git a/plugins/org.eclipse.wst.validation/vf2/org/eclipse/wst/validation/internal/ExtensionConstants.java b/plugins/org.eclipse.wst.validation/vf2/org/eclipse/wst/validation/internal/ExtensionConstants.java
index c0b4bda..759a382 100644
--- a/plugins/org.eclipse.wst.validation/vf2/org/eclipse/wst/validation/internal/ExtensionConstants.java
+++ b/plugins/org.eclipse.wst.validation/vf2/org/eclipse/wst/validation/internal/ExtensionConstants.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2005, 2010 IBM Corporation and others.
+ * Copyright (c) 2005, 2017 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
@@ -45,7 +45,11 @@
 	 * extension point.
 	 */
 	String sourceId = "sourceid"; //$NON-NLS-1$
-	
+	/**
+	 * description - user-visible description for the validator, e.g. for clarifying the contexts in which it would be used
+	 */
+	String description = "description"; //$NON-NLS-1$
+
 	/** 
 	 * version - the version of this definition. The attribute is a simple integer, and if not specified it
 	 * is assumed to be 1. This allows the filter settings to be changed in the future.
diff --git a/plugins/org.eclipse.wst.validation/vf2/org/eclipse/wst/validation/internal/ValidatorExtensionReader.java b/plugins/org.eclipse.wst.validation/vf2/org/eclipse/wst/validation/internal/ValidatorExtensionReader.java
index 7f1b3fe..d959253 100644
--- a/plugins/org.eclipse.wst.validation/vf2/org/eclipse/wst/validation/internal/ValidatorExtensionReader.java
+++ b/plugins/org.eclipse.wst.validation/vf2/org/eclipse/wst/validation/internal/ValidatorExtensionReader.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2007, 2012 IBM Corporation and others.
+ * Copyright (c) 2007, 2017 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
@@ -171,6 +171,7 @@
 			v.setLevel(Validator.Level.Extension);
 			v.setId(id);
 			v.setName(label);
+			v.setDescription(validator.getAttribute(ExtensionConstants.description));
 			v.setBuildValidation(getAttribute(validator, ExtensionConstants.build, true));
 			v.setManualValidation(getAttribute(validator, ExtensionConstants.manual, true));
 			v.setMarkerId(validator.getAttribute(ExtensionConstants.markerId));
diff --git a/plugins/org.eclipse.wst.validation/vf2/org/eclipse/wst/validation/internal/ValidatorMutable.java b/plugins/org.eclipse.wst.validation/vf2/org/eclipse/wst/validation/internal/ValidatorMutable.java
index 5ab29c5..f2f7a59 100644
--- a/plugins/org.eclipse.wst.validation/vf2/org/eclipse/wst/validation/internal/ValidatorMutable.java
+++ b/plugins/org.eclipse.wst.validation/vf2/org/eclipse/wst/validation/internal/ValidatorMutable.java
@@ -1,3 +1,13 @@
+/*******************************************************************************
+ * Copyright (c) 2009, 2017 IBM Corporation and others.
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ *
+ * Contributors:
+ * IBM Corporation - initial API and implementation
+ *******************************************************************************/
 package org.eclipse.wst.validation.internal;
 
 import java.util.HashMap;
@@ -27,6 +37,7 @@
 	private int _changeCountMessages;
 	
 	private final String	_name;
+	private final String	_description;
 	private final String 	_sourceId;
 	private final boolean _isV1;
 	private final boolean _isV2;
@@ -44,6 +55,7 @@
 
 	public ValidatorMutable(Validator validator) {
 		_name = validator.getName();
+		_description = validator.getDescription();
 		_sourceId = validator.getSourceId();
 		_manual = validator.isManualValidation();
 		_build = validator.isBuildValidation();
@@ -90,6 +102,7 @@
 		}
 
 		_name = val._name;
+		_description = val._description;
 		_origBuild = val._origBuild;
 		_origDelegating = val._origDelegating;
 		_origManual = val._origManual;
@@ -111,6 +124,10 @@
 		return _name;
 	}
 
+	public String getDescription() {
+		return _description;
+	}
+
 	public boolean isManualValidation() {
 		return _manual;
 	}
diff --git a/plugins/org.eclipse.wst.validation/xsds/validator.exsd b/plugins/org.eclipse.wst.validation/xsds/validator.exsd
index b03167d..35bc948 100644
--- a/plugins/org.eclipse.wst.validation/xsds/validator.exsd
+++ b/plugins/org.eclipse.wst.validation/xsds/validator.exsd
@@ -106,6 +106,16 @@
                </documentation>
             </annotation>
          </attribute>
+         <attribute name="description" type="string">
+            <annotation>
+               <documentation>
+                  Description of this validator, which should never be the same as the validator&apos;s name.
+               </documentation>
+               <appInfo>
+                  <meta.attribute translatable="true"/>
+               </appInfo>
+            </annotation>
+         </attribute>
       </complexType>
    </element>
 
@@ -382,15 +392,6 @@
 
    <annotation>
       <appInfo>
-         <meta.section type="apiInfo"/>
-      </appInfo>
-      <documentation>
-         Provisional API.
-      </documentation>
-   </annotation>
-
-   <annotation>
-      <appInfo>
          <meta.section type="since"/>
       </appInfo>
       <documentation>
@@ -421,6 +422,15 @@
       </documentation>
    </annotation>
 
+   <annotation>
+      <appInfo>
+         <meta.section type="apiInfo"/>
+      </appInfo>
+      <documentation>
+         Provisional API.
+      </documentation>
+   </annotation>
+
 
    <annotation>
       <appInfo>