Implement QuickDoc for usage messages of user functions

Author: halirutan

CHANGELOG.md

@@ -2,7 +2,6 @@
 
 ## Todo
 
-- Show usage for own functions. "Quick Documentation" on a package symbol will show its usage message if available
 - Better rendering for "Go to Declaration" targets
 - Inspection for using the same variable in the e.g. Module definition list several times
 - Quick fix for adding usages and other messages
@@ -14,6 +13,7 @@
 
 ## Version 3.0
 
+- Quick Documentation lookup for own functions. This will show the usage message of a function if available.
 - Performance improvement through caching
 - Support for Libraries. Libraries are basically a package folder with Mathematica source code. This code is indexed and
 can now be used for completion and navigation. The highlighter shows which functions come from a different file

src/de/halirutan/mathematica/documentation/MathematicaDocumentationProvider.java

@@ -123,7 +123,7 @@ public String generateDoc(PsiElement element, @Nullable PsiElement originalEleme
   private String renderCustomUsageMessage(@NotNull Symbol symbol) {
     final Pair<Symbol, List<String>> usages = UsageMessagesKt.extractUsageMessageString(symbol);
     if (usages.component2().isEmpty()) {
-      return "";
+      return null;
     }
     final String fileName = usages.component1().getContainingFile().getName();
     final String symbolName = symbol.getSymbolName();

src/de/halirutan/mathematica/lang/psi/util/UsageMessages.kt

@@ -1,45 +1,74 @@
+/*
+ * Copyright (c) 2017. Patrick Scheibe
+ *
+ * Permission is hereby granted, free of charge, to any person
+ * obtaining a copy of this software and associated documentation
+ * files (the “Software”), to deal in the Software without
+ * restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the
+ * Software is furnished to do so, subject to the following
+ * conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+ * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+ * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+ * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+ * OTHER DEALINGS IN THE SOFTWARE.
+ */
+
 package de.halirutan.mathematica.lang.psi.util
 
 import com.intellij.openapi.progress.ProgressManager
-import com.intellij.openapi.project.DumbService
 import com.intellij.psi.search.searches.ReferencesSearch
 import com.intellij.psi.util.PsiTreeUtil
 import de.halirutan.mathematica.lang.psi.api.MessageName
 import de.halirutan.mathematica.lang.psi.api.Symbol
 import de.halirutan.mathematica.lang.psi.api.assignment.Set
 import de.halirutan.mathematica.lang.psi.api.string.MString
 
-/**
+/** Provides a the feature of searching for a usage element and extract its usage message string
  *
  * @author patrick (02.12.17).
  */
 
 fun extractUsageMessageString(symbol: Symbol): Pair<Symbol, List<String>> {
   val resolve = symbol.resolve() ?: return Pair(symbol, emptyList())
 
+  // if resolve is a real symbol, then already point to the usage message in another file
+  // this might change in future
+  // TODO: Keep above in mind
   if (resolve is Symbol) {
     return Pair(resolve, doUsageMessageExtract(resolve))
   }
 
-  var result: Pair<Symbol, List<String>> = Pair(symbol, emptyList())
-
-  DumbService.getInstance(symbol.project).runReadActionInSmartMode {
-    val elements = ReferencesSearch.search(resolve)
-    for (elm in elements) {
-      ProgressManager.checkCanceled()
-      if (elm != null && elm.element is Symbol) {
-        val sym = elm.element as Symbol
-        val r = doUsageMessageExtract(sym)
-        if (r.isNotEmpty()) {
-          result = Pair(sym, r)
-          break
-        }
+  // Find all references and look if one of them is a usage message
+  ReferencesSearch.search(resolve).find { psiReference ->
+    ProgressManager.checkCanceled()
+    val elm = psiReference.element ?: return@find false
+    if (elm is Symbol) {
+      val messages = doUsageMessageExtract(elm)
+      if (messages.isNotEmpty()) {
+        return Pair(elm, messages)
       }
     }
+    return@find false
   }
-  return result
+  return Pair(symbol, emptyList())
 }
 
+/**
+ * Takes a symbol that is located at the code `symbol::usage = ...` and extracts the left string. The it splits the
+ * string at "\n" because this often indicates a new usage for a different call pattern. In addition, it removes the
+ * surrounding quotes and the ellipsis character with "..."
+ * @Note The lhs can be a combination of `<>` and this function will process the joined string of all parts
+ */
 private fun doUsageMessageExtract(symbol: Symbol): List<String> {
   if (symbol.parent is MessageName) {
     val messageName = symbol.parent as MessageName