#487 Improve GLSP Server API documentation (#146)

Improve API documentation for service interfaces

Fixed /issues/146

Co-authored-by: Tobias Ortmayr <[email protected]>

Contributed on behalf of STMicroelectronics

CHANGELOG.md

@@ -1,4 +1,14 @@
 # Eclipse GLSP Server Changelog
+## v0.10.0 - Upcoming
+
+### Changes
+
+- [documentation] Improved existing API javadoc and added missing documentation for service interfaces. [#487](https://github.com/eclipse-glsp/glsp-server/pull/146) - Contributed on behalf of STMicroelectronics
+- 
+
+### Breaking Changes
+
+
 
 ## [v0.9.0- 09/12/2021](https://github.com/eclipse-glsp/glsp/releases/tag/0.9.0)
 

plugins/org.eclipse.glsp.graph/src/org/eclipse/glsp/graph/GModelChangeNotifier.java

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2019 EclipseSource and others.
+ * Copyright (c) 2019-2021 EclipseSource and others.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License v. 2.0 which is available at
@@ -21,19 +21,40 @@
 import org.eclipse.emf.ecore.util.EcoreUtil;
 import org.eclipse.glsp.graph.impl.GModelChangeNotifierImpl;
 
+/**
+ * A notifier interface to notify registered {@link GModelListener}s if a {@link GModelElement} changes.
+ * Mostly, changes of the {@link GModelRoot} will be tracked and broadcasted.
+ */
 public interface GModelChangeNotifier {
 
+   /**
+    * Get the GModelChangeNotifier for a given GModelElement.
+    *
+    * @param element The GModelElement to observe for changes.
+    * @return The {@link GModelChangeNotifier} instance that observers the given element.
+    */
    static GModelChangeNotifier get(final GModelElement element) {
       EObject root = EcoreUtil.getRootContainer(element);
       GModelChangeNotifier existingNotifier = (GModelChangeNotifierImpl) EcoreUtil.getExistingAdapter(root,
          GModelChangeNotifierImpl.class);
       return Optional.ofNullable(existingNotifier).orElseGet(() -> create(element));
    }
 
+   /**
+    * Create a new GModelChangeNotifier instance to notify about changes of the given {@link GModelElement}.
+    *
+    * @param element The GModelElement to observe for changes.
+    * @return A new instance of {@link GModelChangeNotifier} that observers the given element.
+    */
    static GModelChangeNotifier create(final GModelElement element) {
       return new GModelChangeNotifierImpl(EcoreUtil.getRootContainer(element));
    }
 
+   /**
+    * Remove an observed {@link GModelElement} from the notifier instance.
+    *
+    * @param element The GModelElement to remove from the observed notifier target.
+    */
    static void remove(final GModelElement element) {
       EObject root = EcoreUtil.getRootContainer(element);
       GModelChangeNotifierImpl existingNotifier = (GModelChangeNotifierImpl) EcoreUtil.getExistingAdapter(root,
@@ -44,8 +65,18 @@ static void remove(final GModelElement element) {
       existingNotifier.unsetTarget(root);
    }
 
+   /**
+    * Add a {@link GModelListener} to the {@link GModelChangeNotifier} to observe GModelElement changes.
+    *
+    * @param listener The listener to add.
+    */
    void addListener(GModelListener listener);
 
+   /**
+    * Remove a {@link GModelListener} from the {@link GModelChangeNotifier} to stop observing GModelElement changes.
+    *
+    * @param listener The listener to remove.
+    */
    void removeListener(GModelListener listener);
 
 }

plugins/org.eclipse.glsp.graph/src/org/eclipse/glsp/graph/GModelIndex.java

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2019 EclipseSource and others.
+ * Copyright (c) 2019-2021 EclipseSource and others.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License v. 2.0 which is available at
@@ -28,18 +28,39 @@
 import org.eclipse.emf.ecore.util.EcoreUtil;
 import org.eclipse.glsp.graph.impl.GModelIndexImpl;
 
+/**
+ * Is used to index all child elements of a {@link GModelRoot} by their id. Offers a set
+ * of query methods to retrieve indexed elements.
+ */
 public interface GModelIndex {
 
+   /**
+    * Returns the GModelIndex instance that contains the root of the given {@link GModelElement}.
+    *
+    * @param element The GModelElement for which an index instance should be returned.
+    * @return The GModelIndex instance that contains the root of the given GModelElement.
+    */
    static GModelIndex get(final GModelElement element) {
       EObject root = EcoreUtil.getRootContainer(element);
       GModelIndex existingIndex = (GModelIndexImpl) EcoreUtil.getExistingAdapter(root, GModelIndexImpl.class);
       return Optional.ofNullable(existingIndex).orElseGet(() -> (create(element)));
    }
 
+   /**
+    * Create a new GModelIndex instance of the root of the given {@link GModelElement}.
+    *
+    * @param element The GModelElement for which a new index instance should be created.
+    * @return A new GModelIndex instance that contains the root of the given GModelElement.
+    */
    static GModelIndex create(final GModelElement element) {
       return new GModelIndexImpl(EcoreUtil.getRootContainer(element));
    }
 
+   /**
+    * Removes the root of the given {@link GModelElement} from an existing GModelIndex instance.
+    *
+    * @param element The GModelElement which root should be removed from the index instance.
+    */
    static void remove(final GModelElement element) {
       EObject root = EcoreUtil.getRootContainer(element);
       GModelIndexImpl existingIndex = (GModelIndexImpl) EcoreUtil.getExistingAdapter(root, GModelIndexImpl.class);
@@ -49,28 +70,70 @@ static void remove(final GModelElement element) {
       existingIndex.unsetTarget(root);
    }
 
+   /**
+    * Returns an optional {@link GModelElement} by its elementId.
+    *
+    * @param elementId The id of the requested {@link GModelElement}.
+    * @return An optional instance of the {@link GModelElement}.
+    */
    Optional<GModelElement> get(String elementId);
 
+   /**
+    * Returns a set of {@link GModelElement} instances by a Collection of elementIds.
+    *
+    * @param elementIds The ids to request the {@link GModelElement} instances.
+    * @return A set of {@link GModelElement}s.
+    */
    Set<GModelElement> getAll(Collection<String> elementIds);
 
+   /**
+    * Returns a collection of all incoming edges for a {@link GModelElement}.
+    *
+    * @param node The requested {@link GModelElement}.
+    * @return A collection of all incoming edges for a {@link GModelElement}.
+    */
    Collection<GEdge> getIncomingEdges(GModelElement node);
 
+   /**
+    * Returns a collection of all outgoing edges for a {@link GModelElement}.
+    *
+    * @param node The requested {@link GModelElement}.
+    * @return A collection of all outgoing edges for a {@link GModelElement}.
+    */
    Collection<GEdge> getOutgoingEdges(GModelElement node);
 
+   /**
+    * Returns a set of all {@link GModelElement} ids contained in this instance of the GModelIndex.
+    *
+    * @return A set of elementIds.
+    */
    Set<String> allIds();
 
+   /**
+    * Returns the contained {@link GModelRoot} in this instance of the GModelIndex.
+    *
+    * @return The contained {@link GModelRoot} instance.
+    */
    GModelElement getRoot();
 
+   /**
+    * Returns the current amount of occurrences of an EClass in this instance of the GModelIndex.
+    *
+    * @param eClass     The EClass to be counted in this instance of the GModelIndex.
+    * @param idProvider A function that provides an id based on the counter result.
+    *
+    * @return The amount of occurrences of an EClass.
+    */
    int getCounter(EClass eClass, Function<Integer, String> idProvider);
 
    /**
     * Returns the first element of type clazz starting from the element with the
     * given id and walking up the parent hierarchy.
     *
-    * @param elementId id of the element to start the search from
-    * @param clazz     class of which the found element should be an instance
-    * @param <T>       type of the element to be found
-    * @return an optional with the element of type clazz or an empty optional
+    * @param elementId The id of the element to start the search from.
+    * @param clazz     The class of which the found element should be an instance.
+    * @param <T>       The type of the element to be found.
+    * @return An optional with the element of type clazz or an empty optional.
     */
    default <T extends GModelElement> Optional<T> findElementByClass(final String elementId, final Class<T> clazz) {
       Optional<GModelElement> element = get(elementId);
@@ -84,10 +147,10 @@ default <T extends GModelElement> Optional<T> findElementByClass(final String el
     * Returns the first element of type clazz starting from the given element and
     * walking up the parent hierarchy.
     *
-    * @param element element to start the search from
-    * @param clazz   class of which the found element should be an instance
-    * @param <T>     type of the element to be found
-    * @return an optional with the element of type clazz or an empty optional
+    * @param element The element to start the search from.
+    * @param clazz   The class of which the found element should be an instance.
+    * @param <T>     The type of the element to be found.
+    * @return An optional with the element of type clazz or an empty optional.
     *
     *
     */
@@ -107,9 +170,9 @@ default <T extends GModelElement> Optional<T> findElementByClass(final GModelEle
     * Returns the first element matching the predicate starting element with the
     * given id and walking up the parent hierarchy.
     *
-    * @param elementId element to start the search from
-    * @param predicate predicate which the element should match
-    * @return an optional with the first element matching the predicate or an empty
+    * @param elementId The element to start the search from
+    * @param predicate The predicate which the element should match
+    * @return An optional with the first element matching the predicate or an empty
     *         optional
     */
    default Optional<GModelElement> findElement(final String elementId, final Predicate<GModelElement> predicate) {
@@ -124,10 +187,10 @@ default Optional<GModelElement> findElement(final String elementId, final Predic
     * Returns the first element matching the predicate starting from the given
     * element and walking up the parent hierarchy.
     *
-    * @param element   element to start the search from
-    * @param predicate predicate which the element should match
-    * @return an optional with the first element matching the predicate or an empty
-    *         optional
+    * @param element   The element to start the search from.
+    * @param predicate The predicate which the element should match.
+    * @return An optional with the first element matching the predicate or an empty
+    *         optional.
     */
    default Optional<GModelElement> findElement(final GModelElement element, final Predicate<GModelElement> predicate) {
       if (element == null) {
@@ -141,15 +204,36 @@ default Optional<GModelElement> findElement(final GModelElement element, final P
       return parent != null ? findElement(parent, predicate) : Optional.empty();
    }
 
+   /**
+    * Returns all elements of the type clazz contained in the {@link GModelRoot}.
+    *
+    * @param <T>   Type of the elements to be returned.
+    * @param clazz The class of which the returned elements should be instances.
+    * @return A set containing the elements of type clazz.
+    */
    default <T extends GModelElement> Set<T> getAllByClass(final Class<T> clazz) {
       return findAll(this.getRoot(), clazz);
    }
 
+   /**
+    * Returns all elements of the type clazz contained in a given parent {@link GModelElement}.
+    *
+    * @param <T>    Type of the elements to be returned.
+    * @param parent The parent element to start the element search from.
+    * @param clazz  The class of which the returned elements should be instances.
+    * @return A set containing the elements of type clazz.
+    */
    default <T extends GModelElement> Set<T> findAll(final GModelElement parent, final Class<T> type) {
       return getStream(parent).flatMap(this::getStream).filter(type::isInstance).map(type::cast)
          .collect(Collectors.toSet());
    }
 
+   /**
+    * Returns a {@link Stream} of all contained {@link GModelElement} in the given {@link GModelElement}.
+    *
+    * @param element The element to retrieve all contained elements as stream.
+    * @return A stream of all elements.
+    */
    default Stream<GModelElement> getStream(final GModelElement element) {
       if (element == null) {
          return Stream.empty();
@@ -160,6 +244,13 @@ default Stream<GModelElement> getStream(final GModelElement element) {
       return Stream.concat(Stream.of(element), element.getChildren().stream());
    }
 
+   /**
+    * Returns the current amount of type occurrences in this instance of the GModelIndex.
+    *
+    * @param eClass The EClass to be counted in this instance of the GModelIndex.
+    *
+    * @return The amount of type occurrences.
+    */
    int getTypeCount(EClass eClass);
 
 }

plugins/org.eclipse.glsp.graph/src/org/eclipse/glsp/graph/GModelListener.java

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2019 EclipseSource and others.
+ * Copyright (c) 2019-2021 EclipseSource and others.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License v. 2.0 which is available at
@@ -17,8 +17,17 @@
 
 import org.eclipse.emf.common.notify.Notification;
 
+/**
+ * A listener to observe changes of the {@link GModelRoot}.
+ * It is typically associated with a {@link GModelChangeNotifier}.
+ */
 public interface GModelListener {
 
+   /**
+    * Triggered if a change to the {@link GModelRoot} has occurred.
+    *
+    * @param notification A description of the change to the GModelRoot.
+    */
    void notifyChanged(Notification notification);
 
 }

plugins/org.eclipse.glsp.graph/src/org/eclipse/glsp/graph/GraphExtension.java

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2019 EclipseSource and others.
+ * Copyright (c) 2019-2021 EclipseSource and others.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License v. 2.0 which is available at
@@ -18,9 +18,13 @@
 import org.eclipse.emf.ecore.EFactory;
 import org.eclipse.emf.ecore.EPackage;
 
+/**
+ * Is used to configure a graph extension for a diagram language. A graph extension
+ * is a custom Ecore model that extends the default GLSP Graph ecore model, e.g by adding new GModelElement types.
+ */
 public interface GraphExtension {
    /**
-    * Unique identifier for this graph extension (Default: NSURI of the Epackage).
+    * Unique identifier for this graph extension (Default: NSURI of the EPackage).
     *
     * @return Id as String
     */
@@ -37,7 +41,7 @@ public interface GraphExtension {
    /**
     * Returns the EFactory for this {@link GraphExtension}.
     *
-    * @return the EFfactory
+    * @return the EFactory
     */
    EFactory getEFactory();
 }

plugins/org.eclipse.glsp.graph/src/org/eclipse/glsp/graph/impl/GModelIndexImpl.java

@@ -1,5 +1,5 @@
 /********************************************************************************
- * Copyright (c) 2019 EclipseSource and others.
+ * Copyright (c) 2019-2021 EclipseSource and others.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License v. 2.0 which is available at
@@ -38,9 +38,15 @@
 import org.eclipse.glsp.graph.GEdge;
 import org.eclipse.glsp.graph.GModelElement;
 import org.eclipse.glsp.graph.GModelIndex;
+import org.eclipse.glsp.graph.GModelRoot;
 
 import com.google.common.base.Preconditions;
 
+/**
+ * Default implementation of {@link GModelIndex}. Registers itself as adapter of the {@link GModelRoot}
+ * to receive change notifications. This enables auto updating of the internal index if a child elements is
+ * added or removed from the {@link GModelRoot}.
+ */
 public class GModelIndexImpl extends ECrossReferenceAdapter implements GModelIndex {
 
    private final Map<String, GModelElement> idToElement = new HashMap<>();

plugins/org.eclipse.glsp.server/src/org/eclipse/glsp/server/actions/ActionDispatcher.java

@@ -22,6 +22,10 @@
 import org.eclipse.glsp.server.disposable.IDisposable;
 import org.eclipse.glsp.server.features.core.model.UpdateModelAction;
 
+/**
+ * The central component that process all {@link Action}s by dispatching them to their designated
+ * handlers.
+ */
 public interface ActionDispatcher extends IDisposable {
 
    /**