Online help for problem markers

* Register a problem marker help provider.
* Calculate a context help topic for each marker and dynamically forward
it to the original online help of the related check.

For the end user, pressing F1 on a marker has the result of opening the
integrated Eclipse help and showing the checkstyle problem description
online.

Fixes #568.

Author: Bananeweizen

net.sf.eclipsecs.core/src/net/sf/eclipsecs/core/builder/CheckstyleMarker.java

@@ -20,6 +20,9 @@
 
 package net.sf.eclipsecs.core.builder;
 
+import org.eclipse.core.resources.IMarker;
+import org.eclipse.core.runtime.CoreException;
+
 import net.sf.eclipsecs.core.CheckstylePlugin;
 
 /**
@@ -45,6 +48,15 @@ public final class CheckstyleMarker {
   public static final String INFO_TYPE = CheckstylePlugin.PLUGIN_ID + ".info"; //$NON-NLS-1$
 
   private CheckstyleMarker() {
-    // NOOP
+    // utility class
+  }
+
+  public static boolean isCheckstyleMarker(IMarker marker) {
+    try {
+      return CheckstyleMarker.MARKER_ID.equals(marker.getType());
+    } catch (CoreException ex) {
+      // ignore
+    }
+    return false;
   }
 }

net.sf.eclipsecs.core/src/net/sf/eclipsecs/core/config/meta/MetadataFactory.java

@@ -176,7 +176,7 @@ private static RuleMetadata createRuleMetadata(ModuleDetails moduleDetails) {
         final String ruleDescription = sThirdPartyRuleGroupMap.get(lookupKey).get("description");
         final int rulePriority = Integer.parseInt(sThirdPartyRuleGroupMap.get(lookupKey)
                 .get("priority"));
-        group = new RuleGroupMetadata(ruleGroupName, ruleDescription, false, rulePriority);
+        group = new RuleGroupMetadata(ruleGroupName, ruleGroupName, ruleDescription, false, rulePriority);
         sRuleGroupMetadata.put(ruleGroupName, group);
       }
     }
@@ -534,9 +534,8 @@ private static void doInitialization() throws CheckstylePluginException {
       try (InputStream metadataStream = classLoader.getResourceAsStream(metadataFile)) {
 
         if (metadataStream != null) {
-
           ResourceBundle metadataBundle = getMetadataI18NBundle(metadataFile, classLoader);
-          parseMetadata(metadataStream, metadataBundle);
+          parseMetadata(metadataStream, metadataBundle, groupId(metadataFile));
         }
       } catch (DocumentException | IOException ex) {
         CheckstyleLog.log(ex, "Could not read metadata " + metadataFile); //$NON-NLS-1$
@@ -546,6 +545,19 @@ private static void doInitialization() throws CheckstylePluginException {
     loadRuleMetadata();
   }
 
+  /**
+   * @param metadataFile
+   * @return
+   */
+  private static String groupId(String metadataFile) {
+    var start = metadataFile.indexOf("checks/") + 7;
+    var end = metadataFile.lastIndexOf("/");
+    if (start >= end) {
+      return "";
+    }
+    return metadataFile.substring(start, end);
+  }
+
   /**
    * Creates RuleMetadata.
    */
@@ -648,7 +660,7 @@ private static ResourceBundle getMetadataI18NBundle(String metadataFile,
     }
   }
 
-  private static void parseMetadata(InputStream metadataStream, ResourceBundle metadataBundle)
+  private static void parseMetadata(InputStream metadataStream, ResourceBundle metadataBundle, String groupId)
           throws DocumentException, CheckstylePluginException {
 
     SAXReader reader = new SAXReader();
@@ -660,7 +672,7 @@ private static void parseMetadata(InputStream metadataStream, ResourceBundle met
 
     for (Element groupEl : groupElements) {
 
-      String groupName = groupEl.attributeValue(XMLTags.NAME_TAG).trim();
+      var groupName = groupEl.attributeValue(XMLTags.NAME_TAG).trim();
       groupName = localize(groupName, metadataBundle);
 
       // process description
@@ -680,7 +692,7 @@ private static void parseMetadata(InputStream metadataStream, ResourceBundle met
           priority = Integer.MAX_VALUE;
         }
 
-        group = new RuleGroupMetadata(groupName, groupDesc, hidden, priority);
+        group = new RuleGroupMetadata(groupId, groupName, groupDesc, hidden, priority);
         sRuleGroupMetadata.put(groupName, group);
       }
 

net.sf.eclipsecs.core/src/net/sf/eclipsecs/core/config/meta/RuleGroupMetadata.java

@@ -28,6 +28,11 @@
  */
 public class RuleGroupMetadata {
 
+  /**
+   * group id, used for online help URL calculation
+   */
+  private final String mGroupId;
+
   /** The name of the group. */
   private String mGroupName;
 
@@ -43,7 +48,8 @@ public class RuleGroupMetadata {
   /** The list of modules belonging to the group. */
   private List<RuleMetadata> mRuleMetadata = new LinkedList<>();
 
-  RuleGroupMetadata(String groupName, String groupDesc, boolean hidden, int priority) {
+  RuleGroupMetadata(String groupId, String groupName, String groupDesc, boolean hidden, int priority) {
+    mGroupId = groupId;
     mGroupName = groupName;
     mDescription = groupDesc;
     mIsHidden = hidden;
@@ -94,4 +100,11 @@ public int getPriority() {
   public final List<RuleMetadata> getRuleMetadata() {
     return mRuleMetadata;
   }
+
+  /**
+   * @return the group id
+   */
+  public String getGroupId() {
+    return mGroupId;
+  }
 }

net.sf.eclipsecs.ui/META-INF/MANIFEST.MF

@@ -9,7 +9,8 @@ Bundle-ActivationPolicy: lazy
 Require-Bundle: net.sf.eclipsecs.core,
  org.eclipse.core.expressions,
  org.eclipse.ui.workbench,
- org.eclipse.jface
+ org.eclipse.jface,
+ org.eclipse.help;bundle-version="3.9.0"
 Bundle-RequiredExecutionEnvironment: JavaSE-11
 Export-Package: net.sf.eclipsecs.ui,
  net.sf.eclipsecs.ui.properties.filter,

net.sf.eclipsecs.ui/plugin.xml

@@ -610,5 +610,18 @@
              module="UpperEllCheck"
              class="net.sf.eclipsecs.ui.quickfixes.misc.UpperEllQuickfix">
        </quickfix>
+   </extension>
+   <extension
+          point="org.eclipse.ui.ide.markerHelp">
+       <markerHelp
+             helpContextProvider="net.sf.eclipsecs.ui.quickfixes.MarkerHelpContextProvider"
+             markerType="net.sf.eclipsecs.core.CheckstyleMarker"
+             matchChildren="false"></markerHelp>
+    </extension>
+    <extension
+          point="org.eclipse.help.contexts">
+       <contextProvider
+             class="net.sf.eclipsecs.ui.quickfixes.MarkerHelpContextProvider">
+       </contextProvider>
     </extension>
 </plugin>

net.sf.eclipsecs.ui/src/net/sf/eclipsecs/ui/quickfixes/MarkerHelpContextProvider.java

@@ -0,0 +1,161 @@
+//============================================================================
+//
+// Copyright (C) 2003-2023 the original author or authors.
+//
+// This library is free software; you can redistribute it and/or
+// modify it under the terms of the GNU Lesser General Public
+// License as published by the Free Software Foundation; either
+// version 2.1 of the License, or (at your option) any later version.
+//
+// This library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+// Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public
+// License along with this library; if not, write to the Free Software
+// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+//
+//============================================================================
+
+package net.sf.eclipsecs.ui.quickfixes;
+
+import org.apache.commons.lang3.StringUtils;
+import org.eclipse.core.resources.IMarker;
+import org.eclipse.ui.IMarkerHelpContextProvider;
+
+import net.sf.eclipsecs.core.builder.CheckstyleMarker;
+import net.sf.eclipsecs.core.config.meta.MetadataFactory;
+
+import org.eclipse.help.AbstractContextProvider;
+import org.eclipse.help.IContext;
+import org.eclipse.help.IHelpResource;
+
+/**
+ * Provides context help for checkstyle markers.
+ */
+public class MarkerHelpContextProvider extends AbstractContextProvider
+        implements IMarkerHelpContextProvider {
+
+  /**
+   * package of the regexp checks
+   */
+  private static final String REGEXP_PACKAGE = "com.puppycrawl.tools.checkstyle.checks.regexp.";
+  /**
+   * suffix of all standard check implementations
+   */
+  private static final String CHECK_SUFFIX = "Check";
+  /**
+   * Common prefix for all Checkstyle marker help contexts. Must be same as plugin id and must end
+   * with a dot.
+   */
+  private static final String PLUGIN_PREFIX = "net.sf.eclipsecs.ui" + ".";
+
+  @Override
+  public String getHelpContextForMarker(IMarker marker) {
+    String module = getModule(marker);
+    if (!module.endsWith(CHECK_SUFFIX)) {
+      return null;
+    }
+    return PLUGIN_PREFIX + StringUtils.removeEnd(StringUtils.substringAfterLast(module, '.'), CHECK_SUFFIX);
+  }
+
+  private String getModule(IMarker marker) {
+    return marker.getAttribute(CheckstyleMarker.MODULE_NAME, StringUtils.EMPTY);
+  }
+
+  @Override
+  public boolean hasHelpContextForMarker(IMarker marker) {
+    if (!CheckstyleMarker.isCheckstyleMarker(marker)) {
+      return false;
+    }
+    if (getModule(marker).startsWith(REGEXP_PACKAGE)) {
+      // regex rules don't provide useful help for understanding and fixing an issue
+      return false;
+    }
+    return true;
+  }
+
+  @Override
+  public IContext getContext(String id, String locale) {
+    var moduleName = StringUtils.substringAfter(id, PLUGIN_PREFIX);
+    return new CheckstyleHelpContext(moduleName);
+  }
+
+  @Override
+  public String[] getPlugins() {
+    return new String[] { "net.sf.eclipsecs.ui" };
+  }
+
+  /**
+   * @param moduleName
+   *          module name
+   * @return online help URL
+   */
+  public static String getOnlineHelp(String moduleName) {
+    var metadata = MetadataFactory.getRuleMetadata(moduleName);
+    if (metadata == null) {
+      return null;
+    }
+    var group = metadata.getGroup().getGroupId().toLowerCase();
+    // some web pages are different to the packages in Checkstyle
+    if ("indentation".equals(group)) {
+      group = "misc";
+    }
+    var file = moduleName.toLowerCase();
+    return "https://checkstyle.org/checks/" + group + "/" + file + ".html#" + moduleName;
+  }
+
+  /**
+   * Help topic forwarding to the online help
+   */
+  private static final class CheckstyleHelpTopic implements IHelpResource {
+    private final String moduleName;
+
+    /**
+     * @param moduleName
+     *          module name
+     */
+    private CheckstyleHelpTopic(String moduleName) {
+      this.moduleName = moduleName;
+    }
+
+    @Override
+    public String getLabel() {
+      return null;
+    }
+
+    @Override
+    public String getHref() {
+      return getOnlineHelp(moduleName);
+    }
+  }
+
+  /**
+   * Dynamically created help context for a checkstyle marker
+   */
+  private static final class CheckstyleHelpContext implements IContext {
+    private final String moduleName;
+
+    /**
+     * @param moduleName
+     */
+    private CheckstyleHelpContext(String moduleName) {
+      this.moduleName = moduleName;
+    }
+
+    @Override
+    public IHelpResource[] getRelatedTopics() {
+      IHelpResource helpResource = new CheckstyleHelpTopic(moduleName);
+      return new IHelpResource[] { helpResource };
+    }
+
+    @Override
+    public String getText() {
+      // must be null, because the help manager will only show the URL immediately when no text is
+      // defined
+      return null;
+    }
+  }
+
+}