384251: Create documentation for context contribution APIrefs/changes/78/7178/2

Bug: 384251
Task-Url: https://bugs.eclipse.org/bugs/show_bug.cgi?id=384251
Change-Id: I41869f8452e8a3d1fabaa7b53fa4dc789dfe030c

2 files changed, 45 insertions, 6 deletions

diff --git a/org.eclipse.mylyn.context.core/schema/contributor.exsd b/org.eclipse.mylyn.context.core/schema/contributor.exsd
index ee0c1f7..5ba3b09 100644
--- a/org.eclipse.mylyn.context.core/schema/contributor.exsd
+++ b/org.eclipse.mylyn.context.core/schema/contributor.exsd
@@ -6,7 +6,9 @@
          <meta.schema plugin="org.eclipse.mylyn.context.core" id="contributor" name="contributor"/>
       </appInfo>
       <documentation>
-         ContextContributor are allowed to persist arbitrary data in context.
+         ContextContributor are used to persist arbitrary data in context zip file. They may be used to store supporting information for elements in context.
+
+For more information please see: http://wiki.eclipse.org/Mylyn/Enriching_Task_Context_with_Breakpoints
       </documentation>
    </annotation>
 
@@ -52,7 +54,7 @@
          <attribute name="name" type="string">
             <annotation>
                <documentation>
-                  
+                  the name of this contributor (i. e. Breakpoints Contributor)
                </documentation>
                <appInfo>
                   <meta.attribute translatable="true"/>
@@ -62,14 +64,14 @@
          <attribute name="id" type="string">
             <annotation>
                <documentation>
-                  
+                  An id for this context contributor. Must be unique among all context contributors.
                </documentation>
             </annotation>
          </attribute>
          <attribute name="class" type="string" use="required">
             <annotation>
                <documentation>
-                  
+                  Reference to the class implementing this contributor. Must be a subclass of org.eclipse.mylyn.context.core.AbstractContextContributor.
                </documentation>
                <appInfo>
                   <meta.attribute kind="java" basedOn="org.eclipse.mylyn.context.core.AbstractContextContributor:"/>
@@ -84,12 +86,40 @@
          <meta.section type="since"/>
       </appInfo>
       <documentation>
-         3.8
+         3.9
       </documentation>
    </annotation>
 
+   <annotation>
+      <appInfo>
+         <meta.section type="examples"/>
+      </appInfo>
+      <documentation>
+         Example plugin.xml code to add a ContextContributor:
+
+&lt;extension point=&quot;org.eclipse.mylyn.context.core.contributor&quot;&gt;
+      &lt;contextContributor
+            class=&quot;org.eclipse.mylyn.custom.MyContributor&quot;
+            name=&quot;My Contributor&quot;
+            id=&quot;org.eclipse.mylyn.custom.contributor&quot;&gt;
+      &lt;/contextContributor&gt;
+&lt;/extension&gt;
+      </documentation>
+   </annotation>
 
 
 
+   <annotation>
+      <appInfo>
+         <meta.section type="copyright"/>
+      </appInfo>
+      <documentation>
+         Copyright (c) 2012 Sebastian Schmidt 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
+      </documentation>
+   </annotation>
 
 </schema>
diff --git a/org.eclipse.mylyn.context.core/src/org/eclipse/mylyn/context/core/IInteractionContextManager.java b/org.eclipse.mylyn.context.core/src/org/eclipse/mylyn/context/core/IInteractionContextManager.java
index de48c90..56098da 100644
--- a/org.eclipse.mylyn.context.core/src/org/eclipse/mylyn/context/core/IInteractionContextManager.java
+++ b/org.eclipse.mylyn.context.core/src/org/eclipse/mylyn/context/core/IInteractionContextManager.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2004, 2009 Tasktop Technologies and others.
+ * Copyright (c) 2004, 2009, 2012 Tasktop Technologies 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
@@ -7,6 +7,7 @@
  *
  * Contributors:
  *     Tasktop Technologies - initial API and implementation
+ *     Sebastian Schmidt - bug 155333
  *******************************************************************************/
 
 package org.eclipse.mylyn.context.core;
@@ -94,6 +95,14 @@ public interface IInteractionContextManager {
 	public void setContextCapturePaused(boolean paused);
 
 	/**
+	 * Returns additional context data stored among the given context using the given identifier. Use
+	 * {@link IContextContributor} to store additional data.
+	 * 
+	 * @param context
+	 *            Context to query for additional data
+	 * @param identifier
+	 *            Identifier used to store the requested data
+	 * @return InputStream content of the requested file or null if not existent
 	 * @since 3.9
 	 */
 	public InputStream getAdditionalContextData(IInteractionContext context, String identifier);