Standardises function hover

- Makes hover more robust
- Adds extensive unittests for hover support of functions
- Improves documentation of function hover

Author: gnikit

CHANGELOG.md

@@ -2,14 +2,19 @@
 
 ## 2.2.2
 
+### Changed
+
+- Changed the way function hover messages are displayed, now signatures are standardised
+  ([gnikit/fortls#47](https://github.com/gnikit/fortls/issues/47))
+
 ### Fixed
 
 - Fixed hovering over functions displaying as theire result types
   ([gnikit/fortls#22](https://github.com/gnikit/fortls/issues/22))
-- Fixed function hovering signature now standardised
-  ([#47](https://github.com/hansec/fortran-language-server/issues/47))
 - Fixed function modifiers not displaying upon hover
   ([gnikit/fortls#48](https://github.com/gnikit/fortls/issues/48))
+- Fixed function hover when returning arrays
+  ([gnikit/fortls#50](https://github.com/gnikit/fortls/issues/50))
 
 ## 2.2.1
 

fortls/objects.py

@@ -976,7 +976,7 @@ def get_hover(self, long=False, include_doc=True, drop_arg=-1):
         keyword_list = get_keywords(self.keywords)
         keyword_list.append(f"{self.get_desc()} ")
         hover_array = [" ".join(keyword_list) + sub_sig]
-        self.get_docs_full(hover_array, long, include_doc, drop_arg)
+        hover_array = self.get_docs_full(hover_array, long, include_doc, drop_arg)
         return "\n ".join(hover_array), long
 
     def get_docs_full(
@@ -994,6 +994,7 @@ def get_docs_full(
                 doc_str = arg_obj.get_documentation()
                 if include_doc and (doc_str is not None):
                     hover_array += doc_str.splitlines()
+        return hover_array
 
     def get_signature(self, drop_arg=-1):
         arg_sigs = []
@@ -1136,22 +1137,63 @@ def get_desc(self):
     def is_callable(self):
         return False
 
-    def get_hover(self, long=False, include_doc=True, drop_arg=-1):
+    def get_hover(
+        self, long: bool = False, include_doc: bool = True, drop_arg: int = -1
+    ) -> tuple[str, bool]:
+        """Construct the hover message for a FUNCTION.
+        Two forms are produced here the `long` i.e. the normal for hover requests
+
+        ```
+        [MODIFIERS] FUNCTION NAME([ARGS]) RESULT(RESULT_VAR)
+          TYPE, [ARG_MODIFIERS] :: [ARGS]
+          TYPE, [RESULT_MODIFIERS] :: RESULT_VAR
+        ```
+
+        note: intrinsic functions will display slightly different,
+        `RESULT_VAR` and its `TYPE` might not always be present
+
+        short form, used when functions are arguments in functions and subroutines:
+
+        ```
+        FUNCTION NAME([ARGS]) :: ARG_LIST_NAME
+        ```
+
+        Parameters
+        ----------
+        long : bool, optional
+            toggle between long and short hover results, by default False
+        include_doc : bool, optional
+            if to include any documentation, by default True
+        drop_arg : int, optional
+            Ignore argument at position `drop_arg` in the argument list, by default -1
+
+        Returns
+        -------
+        tuple[str, bool]
+            String representative of the hover message and the `long` flag used
+        """
         fun_sig, _ = self.get_snippet(drop_arg=drop_arg)
-        fun_sig += f" RESULT({self.result_name})"
-        keyword_list = []
-        if self.result_type:
-            keyword_list.append(self.result_type)
-        keyword_list += get_keywords(self.keywords)
+        # short hover messages do not include the result()
+        fun_sig += f" RESULT({self.result_name})" if long else ""
+        keyword_list = get_keywords(self.keywords)
         keyword_list.append("FUNCTION")
 
         hover_array = [f"{' '.join(keyword_list)} {fun_sig}"]
-        self.get_docs_full(hover_array, long, include_doc, drop_arg)
+        hover_array = self.get_docs_full(hover_array, long, include_doc, drop_arg)
+        # Only append the return value if using long form
+        if self.result_obj and long:
+            arg_doc, _ = self.result_obj.get_hover(include_doc=False)
+            hover_array.append(f"{arg_doc} :: {self.result_obj.name}")
+        # intrinsic functions, where the return type is missing but can be inferred
+        elif self.result_type and long:
+            # prepend type to function signature
+            hover_array[0] = f"{self.result_type} {hover_array[0]}"
         return "\n ".join(hover_array), long
 
     def get_interface(self, name_replace=None, change_arg=-1, change_strings=None):
         fun_sig, _ = self.get_snippet(name_replace=name_replace)
         fun_sig += f" RESULT({self.result_name})"
+        # XXX:
         keyword_list = []
         if self.result_type:
             keyword_list.append(self.result_type)

fortls/parse_fortran.py

@@ -290,7 +290,7 @@ def read_var_def(line: str, type_word: str = None, fun_only: bool = False):
 
 
 def read_fun_def(
-    line: str, result: RESULT_sig = RESULT_sig(), mod_flag: bool = False
+    line: str, result: RESULT_sig = None, mod_flag: bool = False
 ) -> tuple[Literal["fun"], FUN_sig] | None:
     """Attempt to read FUNCTION definition line
 
@@ -345,9 +345,11 @@ def read_fun_def(
     # Extract if possible the variable name of the result()
     trailing_line = trailing_line.strip()
     results_match = RESULT_REGEX.match(trailing_line)
+    if result is None:
+        result = RESULT_sig()
     if results_match:
         result.name = results_match.group(1).strip().lower()
-    return "fun", FUN_sig(name, args, keywords, mod_flag, result=result)
+    return "fun", FUN_sig(name, args, keywords, mod_flag, result)
 
 
 def read_sub_def(line: str, mod_flag: bool = False):

test/test_server.py

@@ -579,6 +579,11 @@ def check_return(result_array, checks):
     string += hover_req(file_path, 12, 12)
     string += hover_req(file_path, 18, 19)
     string += hover_req(file_path, 23, 34)
+    string += hover_req(file_path, 28, 11)
+    string += hover_req(file_path, 34, 21)
+    string += hover_req(file_path, 46, 11)
+    string += hover_req(file_path, 51, 11)
+    string += hover_req(file_path, 55, 11)
     file_path = test_dir / "hover" / "recursive.f90"
     string += hover_req(file_path, 9, 40)
     file_path = test_dir / "subdir" / "test_submod.F90"
@@ -604,34 +609,54 @@ def check_return(result_array, checks):
         "DOUBLE PRECISION, PARAMETER :: somevar = 23.12",
         "DOUBLE PRECISION, PARAMETER :: some = 1e-19",
         "INTEGER, POINTER",
-        """INTEGER FUNCTION fun1(arg) RESULT(fun1)
- INTEGER, INTENT(IN) :: arg""",
-        """INTEGER FUNCTION fun2(arg) RESULT(fun2)
- INTEGER, INTENT(IN) :: arg""",
-        """INTEGER FUNCTION fun3(arg) RESULT(retval)
- INTEGER, INTENT(IN) :: arg""",
-        """INTEGER FUNCTION fun4(arg) RESULT(retval)
- INTEGER, INTENT(IN) :: arg""",
+        """FUNCTION fun1(arg) RESULT(fun1)
+ INTEGER, INTENT(IN) :: arg
+ INTEGER :: fun1""",
+        """FUNCTION fun2(arg) RESULT(fun2)
+ INTEGER, INTENT(IN) :: arg
+ INTEGER :: fun2""",
+        """FUNCTION fun3(arg) RESULT(retval)
+ INTEGER, INTENT(IN) :: arg
+ INTEGER :: retval""",
+        """FUNCTION fun4(arg) RESULT(retval)
+ INTEGER, INTENT(IN) :: arg
+ INTEGER :: retval""",
         # Notice that the order of the modifiers does not match the source code
         # This is part of the test, ideally they would be identical but previously
         # any modifiers before the type would be discarded
-        """INTEGER PURE ELEMENTAL FUNCTION fun5(arg) RESULT(retval)
- INTEGER, INTENT(IN) :: arg""",
+        """PURE ELEMENTAL FUNCTION fun5(arg) RESULT(retval)
+ INTEGER, INTENT(IN) :: arg
+ INTEGER :: retval""",
+        """FUNCTION fun6(arg) RESULT(retval)
+ INTEGER, INTENT(IN) :: arg
+ INTEGER, DIMENSION(10,10) :: retval""",
+        """PURE FUNCTION outer_product(x, y) RESULT(outer_product)
+ REAL, DIMENSION(:), INTENT(IN) :: x
+ REAL, DIMENSION(:), INTENT(IN) :: y
+ REAL, DIMENSION(SIZE(X), SIZE(Y)) :: outer_product""",
+        """FUNCTION dlamch(cmach) RESULT(dlamch)
+ CHARACTER :: CMACH""",
+        """FUNCTION fun7() RESULT(val)
+ TYPE(c_ptr) :: val""",
+        """TYPE(c_ptr) FUNCTION c_loc(x) RESULT(c_loc)""",
         """RECURSIVE SUBROUTINE recursive_assign_descending(node, vector, current_loc)
  TYPE(tree_inode), POINTER, INTENT(IN) :: node
  INTEGER, DIMENSION(:), INTENT(INOUT) :: vector
  INTEGER, INTENT(INOUT) :: current_loc""",
-        # TODO: more tests to add from functions
-        """REAL FUNCTION point_dist(a, b) RESULT(distance)
+        """FUNCTION point_dist(a, b) RESULT(distance)
  TYPE(point), INTENT(IN) :: a
- TYPE(point), INTENT(IN) :: b""",
-        """LOGICAL FUNCTION is_point_equal_a(a, b) RESULT(is_point_equal_a)
+ TYPE(point), INTENT(IN) :: b
+ REAL :: distance""",
+        """FUNCTION is_point_equal_a(a, b) RESULT(is_point_equal_a)
  TYPE(point), INTENT(IN) :: a
- TYPE(point), INTENT(IN) :: b""",
-        """REAL FUNCTION foo2(f, g, h) RESULT(arg3)
- REAL FUNCTION f(x) RESULT(z) :: f
- REAL FUNCTION g(x) RESULT(z) :: g
- REAL FUNCTION h(x) RESULT(z) :: h""",
+ TYPE(point), INTENT(IN) :: b
+ LOGICAL :: is_point_equal_a""",
+        # Could be subject to change
+        """FUNCTION foo2(f, g, h) RESULT(arg3)
+ FUNCTION f(x) :: f
+ FUNCTION g(x) :: g
+ FUNCTION h(x) :: h
+ REAL :: arg3""",
     )
     assert len(ref_results) == len(results) - 1
     check_return(results[1:], ref_results)

test/test_source/hover/functions.f90

@@ -25,3 +25,33 @@ pure integer elemental function fun5(arg) result(retval)
     integer, intent(in) :: arg
 end function fun5
 
+! function with type on definition and return
+function fun6(arg) result(retval)
+    integer, intent(in) :: arg
+    integer, dimension(10,10) :: retval
+end function fun6
+
+! functions with complex result type
+pure function outer_product(x, y)
+    real, dimension(:), intent(in) :: x, y
+    real, dimension(size(x), size(y)) :: outer_product
+    integer :: i, j
+    forall (i=1:size(x))
+        forall (j=1:size(y))
+            outer_product(i, j) = x(i) * y(j)
+        end forall
+    end forall
+end function outer_product
+
+! functions with no result type, common in interfaces
+function dlamch(CMACH)
+    character :: CMACH
+end function dlamch
+
+! intrinsic functions like c_loc display a return type
+function fun7() result(val)
+    use, intrinsic :: iso_c_binding
+    integer, dimension(1), target :: ar
+    type(c_ptr) :: val
+    val = c_loc(ar)
+end function fun7