Comment documentation hover formatting works different between standard lib and user code

[sm11963]

Describe the bug The hover showing a nice formatted version of documentation comment for functions works very different for standard lib and user code. Html tags seem to work perfectly for the standard lib, but get completely stripped out from user code. See the screenshots for a more effective description.

To Reproduce

1. Create a simple PHP file with a function like so:

   
   <?php 

function mysubstr(string $string, int $offset, ?int $length) { return substr($string, $offset, $length); }

2. Command + Click on `substr` to go to the declaration of `substr`.
3. Copy the doc comment of `substr`
4. Paste the copied doc comment as the doc comment for `mysubstr`. You should end up with:
```php,lines=10
/**
 * Return part of a string or false on failure. For PHP8.0+ only string is returned
 * @link https://php.net/manual/en/function.substr.php
 * @param string $string <p>
 * The input string.
 * </p>
 * @param int $offset <p>
 * If start is non-negative, the returned string
 * will start at the start'th position in
 * string, counting from zero. For instance,
 * in the string 'abcdef', the character at
 * position 0 is 'a', the
 * character at position 2 is
 * 'c', and so forth.
 * </p>
 * <p>
 * If start is negative, the returned string
 * will start at the start'th character
 * from the end of string.
 * </p>
 * <p>
 * If string is less than or equal to
 * start characters long, false will be returned.
 * </p>
 * <p>
 * Using a negative start
 * </p>
 * <pre>
 * <code>
 * $rest = substr("abcdef", -1);    // returns "f"
 * $rest = substr("abcdef", -2);    // returns "ef"
 * $rest = substr("abcdef", -3, 1); // returns "d"
 * </code>
 * </pre>
 * @param int|null $length [optional] <p>
 * If length is given and is positive, the string
 * returned will contain at most length characters
 * beginning from start (depending on the length of
 * string).
 * </p>
 * <p>
 * If length is given and is negative, then that many
 * characters will be omitted from the end of string
 * (after the start position has been calculated when a
 * start is negative). If
 * start denotes a position beyond this truncation,
 * an empty string will be returned.
 * </p>
 * <p>
 * If length is given and is 0,
 * false or null an empty string will be returned.
 * </p>
 * Using a negative length:
 * <pre>
 * <code>
 * $rest = substr("abcdef", 0, -1);  // returns "abcde"
 * $rest = substr("abcdef", 2, -1);  // returns "cde"
 * $rest = substr("abcdef", 4, -4);  // returns false
 * $rest = substr("abcdef", -3, -1); // returns "de"
 * </code>
 * </pre>
 */
function mysubstr(string $string, int $offset, ?int $length) {
    return substr($string, $offset, $length);
}

5. Compare the hover tooltip displayed when hovering over mysubstr and substr. You should see that for mysubstr much of the content from the doc comment is removed even though they are exactly the same and it looks good for substr.

Expected behavior I would expect that given the same doc comments, the hover tooltip would show the same content.

Screenshots Hover tooltip in the standard lib:

Hover tooltip for copied doc comment in example code:

Just to confirm hover tooltip for substr in my example code:

Platform and version MacOS 14.6.1, VSCode 1.93.1, Intelephense v1.12.6

[bmewburn]

Only markdown is supported in docs. The built-in stubs get converted to markdown. Perhaps a setting could be provided to convert user html docs to markdown.

[sm11963]

Got it, yeah markdown is definitely better (at least imo).

I only stumbled on this because code blocks weren't working they way I expected (I think I'm still experiencing this https://github.com/bmewburn/vscode-intelephense/issues/563), so I went off looking for an example for how to get it working from the source 😄.

Maybe it would be better to convert the built-in stubs to markdown for consistency and good examples?