feat: Change hover to use MarkupContent

MarkedString[] has been deprecated so we switch
to full Markdown syntax for hover messages

Fixes #45

Author: gnikit

fortls/intrinsics.py

@@ -71,7 +71,7 @@ def get_signature(self):
         return call_sig, self.doc_str, arg_sigs
 
     def get_hover(self, long=False):
-        return self.doc_str, False
+        return self.doc_str, None, False
 
     def is_callable(self):
         if self.type == 2:

fortls/langserver.py

@@ -490,9 +490,10 @@ def build_comp(
             comp_obj["detail"] = candidate.get_desc()
             if call_sig is not None:
                 comp_obj["detail"] += " " + call_sig
-            doc_str, _ = candidate.get_hover()
-            if doc_str is not None:
-                comp_obj["documentation"] = doc_str
+            # TODO: doc_str should probably be appended, see LSP standard
+            hover_msg, doc_str, _ = candidate.get_hover()
+            if hover_msg is not None:
+                comp_obj["documentation"] = hover_msg
             return comp_obj
 
         # Get parameters from request
@@ -1035,11 +1036,13 @@ def serve_definition(self, request: dict):
         return None
 
     def serve_hover(self, request: dict):
-        def create_hover(string: str, highlight: bool):
-            if highlight:
-                return {"language": self.hover_language, "value": string}
-            else:
-                return string
+        def create_hover(string: str, docs: str | None, fortran: bool):
+            msg = string
+            if fortran:
+                msg = f"```{self.hover_language}\n{string}\n```"
+            if docs:  # if docs is not None or ""
+                msg += f"\n-----\n{docs}"
+            return msg
 
         def create_signature_hover():
             sig_request = request.copy()
@@ -1057,7 +1060,8 @@ def create_signature_hover():
                             f"{arg_doc[:doc_split]} :: "
                             f"{arg_info['label']}{arg_doc[doc_split:]}"
                         )
-                    return create_hover(arg_string, True)
+                    # TODO: check if correct. I think it's not
+                    return create_hover(arg_string, None, True)
             except:
                 pass
 
@@ -1066,7 +1070,7 @@ def create_signature_hover():
         uri: str = params["textDocument"]["uri"]
         def_line: int = params["position"]["line"]
         def_char: int = params["position"]["character"]
-        path = path_from_uri(uri)
+        path: str = path_from_uri(uri)
         file_obj = self.workspace.get(path)
         if file_obj is None:
             return None
@@ -1075,41 +1079,40 @@ def create_signature_hover():
         if var_obj is None:
             return None
         # Construct hover information
-        var_type = var_obj.get_type()
+        var_type: int = var_obj.get_type()
         hover_array = []
         if var_type in (SUBROUTINE_TYPE_ID, FUNCTION_TYPE_ID):
-            hover_str, highlight = var_obj.get_hover(long=True)
-            hover_array.append(create_hover(hover_str, highlight))
+            hover_str, docs, highlight = var_obj.get_hover(long=True)
+            hover_array.append(create_hover(hover_str, docs, highlight))
         elif var_type == INTERFACE_TYPE_ID:
             for member in var_obj.mems:
-                hover_str, highlight = member.get_hover(long=True)
+                hover_str, docs, highlight = member.get_hover(long=True)
                 if hover_str is not None:
-                    hover_array.append(create_hover(hover_str, highlight))
+                    hover_array.append(create_hover(hover_str, docs, highlight))
         elif var_type == VAR_TYPE_ID:
             # Unless we have a Fortran literal include the desc in the hover msg
             # See get_definition for an explanation about this default name
             if not var_obj.desc.startswith(FORTRAN_LITERAL):
-                hover_str, highlight = var_obj.get_hover()
-                hover_array.append(create_hover(hover_str, highlight))
+                hover_str, docs, highlight = var_obj.get_hover()
+                hover_array.append(create_hover(hover_str, docs, highlight))
             # Hover for Literal variables
             elif var_obj.desc.endswith("REAL"):
-                hover_array.append(create_hover("REAL", True))
+                hover_array.append(create_hover("REAL", None, True))
             elif var_obj.desc.endswith("INTEGER"):
-                hover_array.append(create_hover("INTEGER", True))
+                hover_array.append(create_hover("INTEGER", None, True))
             elif var_obj.desc.endswith("LOGICAL"):
-                hover_array.append(create_hover("LOGICAL", True))
+                hover_array.append(create_hover("LOGICAL", None, True))
             elif var_obj.desc.endswith("STRING"):
                 hover_str = f"CHARACTER(LEN={len(var_obj.name)-2})"
-                hover_array.append(create_hover(hover_str, True))
+                hover_array.append(create_hover(hover_str, None, True))
 
             # Include the signature if one is present e.g. if in an argument list
             if self.hover_signature:
-                hover_str = create_signature_hover()
+                hover_str: str | None = create_signature_hover()
                 if hover_str is not None:
                     hover_array.append(hover_str)
-        #
         if len(hover_array) > 0:
-            return {"contents": hover_array}
+            return {"contents": {"kind": "markdown", "value": "\n".join(hover_array)}}
         return None
 
     def serve_implementation(self, request: dict):

fortls/objects.py

@@ -409,8 +409,8 @@ def get_placeholders(arg_list: list[str]):
     def get_documentation(self):
         return self.doc_str
 
-    def get_hover(self, long=False, include_doc=True, drop_arg=-1):
-        return None, False
+    def get_hover(self, long=False, drop_arg=-1) -> tuple[str | None, str | None, bool]:
+        return None, None, False
 
     def get_signature(self, drop_arg=-1):
         return None, None, None
@@ -920,30 +920,52 @@ def get_snippet(self, name_replace=None, drop_arg=-1):
     def get_desc(self):
         return "SUBROUTINE"
 
-    def get_hover(self, long=False, include_doc=True, drop_arg=-1):
+    def get_hover(self, long=False, drop_arg=-1):
         sub_sig, _ = self.get_snippet(drop_arg=drop_arg)
         keyword_list = get_keywords(self.keywords)
         keyword_list.append(f"{self.get_desc()} ")
         hover_array = [" ".join(keyword_list) + sub_sig]
-        hover_array = self.get_docs_full(hover_array, long, include_doc, drop_arg)
-        return "\n ".join(hover_array), long
+        hover_array, docs = self.get_docs_full(hover_array, long, drop_arg)
+        return "\n ".join(hover_array), "   \n".join(docs), long
 
     def get_docs_full(
-        self, hover_array: list[str], long=False, include_doc=True, drop_arg=-1
-    ):
+        self, hover_array: list[str], long=False, drop_arg=-1
+    ) -> tuple[list[str], list[str]]:
+        """Construct the full documentation with the code signature and the
+        documentation string + the documentation of any arguments.
+
+        Parameters
+        ----------
+        hover_array : list[str]
+            The list of strings to append the documentation to.
+        long : bool, optional
+            Whether or not to fetch the docs of the arguments, by default False
+        drop_arg : int, optional
+            Whether or not to drop certain arguments from the results, by default -1
+
+        Returns
+        -------
+        tuple[list[str], list[str]]
+            Tuple containing the Fortran signature that should be in code blocks
+            and the documentation string that should be in normal Markdown.
+        """
+        doc_strs: list[str] = []
         doc_str = self.get_documentation()
-        if include_doc and doc_str is not None:
-            hover_array[0] += "\n" + doc_str
+        if doc_str is not None:
+            doc_strs.append(doc_str)
         if long:
+            has_args = True
             for i, arg_obj in enumerate(self.arg_objs):
                 if arg_obj is None or i == drop_arg:
                     continue
-                arg_doc, _ = arg_obj.get_hover(include_doc=False)
-                hover_array.append(f"{arg_doc} :: {arg_obj.name}")
-                doc_str = arg_obj.get_documentation()
-                if include_doc and (doc_str is not None):
-                    hover_array += doc_str.splitlines()
-        return hover_array
+                arg, doc_str, _ = arg_obj.get_hover()
+                hover_array.append(arg)
+                if doc_str:  # If doc_str is not None or ""
+                    if has_args:
+                        doc_strs.append("\n**Parameters:**  ")
+                        has_args = False
+                    doc_strs.append(f"`{arg_obj.name}` {doc_str}")
+        return hover_array, doc_strs
 
     def get_signature(self, drop_arg=-1):
         arg_sigs = []
@@ -964,14 +986,15 @@ def get_signature(self, drop_arg=-1):
         call_sig, _ = self.get_snippet()
         return call_sig, self.get_documentation(), arg_sigs
 
+    # TODO: fix this
     def get_interface_array(
         self, keywords: list[str], signature: str, change_arg=-1, change_strings=None
     ):
         interface_array = [" ".join(keywords) + signature]
         for i, arg_obj in enumerate(self.arg_objs):
             if arg_obj is None:
                 return None
-            arg_doc, _ = arg_obj.get_hover(include_doc=False)
+            arg_doc, docs, _ = arg_obj.get_hover()
             if i == change_arg:
                 i0 = arg_doc.lower().find(change_strings[0].lower())
                 if i0 >= 0:
@@ -1087,8 +1110,8 @@ def is_callable(self):
         return False
 
     def get_hover(
-        self, long: bool = False, include_doc: bool = True, drop_arg: int = -1
-    ) -> tuple[str, bool]:
+        self, long: bool = False, drop_arg: int = -1
+    ) -> tuple[str, str, bool]:
         """Construct the hover message for a FUNCTION.
         Two forms are produced here the `long` i.e. the normal for hover requests
 
@@ -1107,8 +1130,6 @@ def get_hover(
         ----------
         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
 
@@ -1124,17 +1145,21 @@ def get_hover(
         keyword_list.append("FUNCTION")
 
         hover_array = [f"{' '.join(keyword_list)} {fun_sig}"]
-        hover_array = self.get_docs_full(hover_array, long, include_doc, drop_arg)
+        hover_array, docs = self.get_docs_full(hover_array, long, 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}")
+            # Parse the documentation from the result variable
+            arg_doc, doc_str, _ = self.result_obj.get_hover()
+            if doc_str is not None:
+                docs.append(f"\n**Return:**  \n`{self.result_obj.name}`{doc_str}")
+            hover_array.append(arg_doc)
         # 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
+        return "\n ".join(hover_array), "  \n".join(docs), long
 
+    # TODO: fix this
     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})"
@@ -1149,7 +1174,7 @@ def get_interface(self, name_replace=None, change_arg=-1, change_strings=None):
             keyword_list, fun_sig, change_arg, change_strings
         )
         if self.result_obj is not None:
-            arg_doc, _ = self.result_obj.get_hover(include_doc=False)
+            arg_doc, docs, _ = self.result_obj.get_hover()
             interface_array.append(f"{arg_doc} :: {self.result_obj.name}")
         name = self.name
         if name_replace is not None:
@@ -1656,18 +1681,17 @@ def get_snippet(self, name_replace=None, drop_arg=-1):
         # Normal variable
         return None, None
 
-    def get_hover(self, long=False, include_doc=True, drop_arg=-1):
+    def get_hover(self, long=False, drop_arg=-1) -> tuple[str, str, bool]:
         doc_str = self.get_documentation()
         # In associated blocks we need to fetch the desc and keywords of the
         # linked object
         hover_str = ", ".join([self.get_desc()] + self.get_keywords())
-        # TODO: at this stage we can mae this lowercase
-        # Add parameter value in the output
+        # If this is not a preprocessor variable, we can append the variable name
+        if not hover_str.startswith("#"):
+            hover_str += f" :: {self.name}"
         if self.is_parameter() and self.param_val:
-            hover_str += f" :: {self.name} = {self.param_val}"
-        if include_doc and (doc_str is not None):
-            hover_str += "\n {}".format("\n ".join(doc_str.splitlines()))
-        return hover_str, True
+            hover_str += f" = {self.param_val}"
+        return hover_str, doc_str, True
 
     def get_keywords(self):
         # TODO: if local keywords are set they should take precedence over link_obj
@@ -1803,45 +1827,34 @@ def get_documentation(self):
             return self.link_obj.get_documentation()
         return self.doc_str
 
-    def get_hover(self, long=False, include_doc=True, drop_arg=-1):
-        doc_str = self.get_documentation()
-        if long:
-            if self.link_obj is None:
-                sub_sig, _ = self.get_snippet()
-                hover_str = f"{self.get_desc()} {sub_sig}"
-                if include_doc and (doc_str is not None):
-                    hover_str += f"\n{doc_str}"
-            else:
-                link_hover, _ = self.link_obj.get_hover(
-                    long=True, include_doc=include_doc, drop_arg=self.drop_arg
-                )
-                hover_split = link_hover.splitlines()
-                call_sig = hover_split[0]
-                paren_start = call_sig.rfind("(")
-                link_name_len = len(self.link_obj.name)
-                call_sig = (
-                    call_sig[: paren_start - link_name_len]
-                    + self.name
-                    + call_sig[paren_start:]
-                )
-                hover_split = hover_split[1:]
-                if include_doc and (self.doc_str is not None):
-                    # Replace linked docs with current object's docs
-                    if (len(hover_split) > 0) and (hover_split[0].count("!!") > 0):
-                        for (i, hover_line) in enumerate(hover_split):
-                            if hover_line.count("!!") == 0:
-                                hover_split = hover_split[i:]
-                                break
-                        else:  # All lines are docs
-                            hover_split = []
-                    hover_split = [self.doc_str] + hover_split
-                hover_str = "\n".join([call_sig] + hover_split)
-            return hover_str, True
-        else:
+    def get_hover(self, long=False, drop_arg=-1) -> tuple[str, str, bool]:
+        docs = self.get_documentation()
+        if not long:
             hover_str = ", ".join([self.desc] + get_keywords(self.keywords))
-            if include_doc and (doc_str is not None):
-                hover_str += f"\n{doc_str}"
-            return hover_str, True
+            return hover_str, docs, True
+        # Long hover message
+        if self.link_obj is None:
+            sub_sig, _ = self.get_snippet()
+            hover_str = f"{self.get_desc()} {sub_sig}"
+        else:
+            link_msg, link_docs, _ = self.link_obj.get_hover(
+                long=True, drop_arg=self.drop_arg
+            )
+            # Replace the name of the linked object with the name of this object
+            hover_str = link_msg.replace(self.link_obj.name, self.name, 1)
+            if isinstance(link_docs, str):
+                # Get just the docstring of the link, if any, no args
+                link_doc_top = self.link_obj.get_documentation()
+                # Replace the linked objects topmost documentation with the
+                # documentation of the procedure pointer if one is present
+                if link_doc_top is not None:
+                    docs = link_docs.replace(link_doc_top, docs, 1)
+                # If no top docstring is present at the linked object but there
+                # are docstrings for the arguments, add them to the end of the
+                # documentation for this object
+                elif link_docs:
+                    docs += "  \n" + link_docs
+        return hover_str, docs, True
 
     def get_signature(self, drop_arg=-1):
         if self.link_obj is not None: