Format of API description in pop-up broken

[lmoellendorf]

Hi, I am developing a library to use LEGO Mindstorms sensors with Arduino and mBot Ranger.

In Arduino IDE v2 my API comments are shown in pop ups which is great! However, I have an issue with formatting.

E.g. this comment:

		/**
		 * Average:
		 *
		 * The average is a weighted average of the bits set to 1 based
		 * on the position.
		 * i.e. left most bit has weight of 10, second bit has weight
		 * of 20.
		 *
		 * The diagrams below explains the line scenario and the
		 * Average returned.
		 *
		 * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
		 * Suppose your line is narrow and only under the sensor 5.
		 * I.e. all the 8 sensors except the 5th sensor will return
		 * zero value. And the 5 th bit will be 1.
		 *
		 * <pre>
		 *                             XXXXX
		 *                             XXXXX
		 *             +---+---+---+---+---+---+---+---+
		 *             | W | W | W | W | B | W | W | W |
		 *             +---+---+---+---+---+---+---+---+
		 *                             XXXXX
		 *                             XXXXX
		 * </pre>
		 *
		 * The ‘Average’ returned in this case
		 * will be 50, calculated as: (0+0+0+0+50+0+0+0)/1
		 * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
		 * Suppose, your line is wider, and 4 sensors are over the
		 * line.
		 *
		 * <pre>
		 *                     XXXXXXXXXXXXXXXXX
		 *                     XXXXXXXXXXXXXXXXX
		 *             +---+---+---+---+---+---+---+---+
		 *             | W | W | B | B | B | B | W | W |
		 *             +---+---+---+---+---+---+---+---+
		 *                     XXXXXXXXXXXXXXXXX
		 *                     XXXXXXXXXXXXXXXXX
		 * </pre>
		 *
		 * The ‘Average’ returned in this case will be 45, calculated
		 * as: (0+0+30+40+50+60+0+0)/4
		 * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
		 * <pre>
		 *                                         XXXXX
		 *                                         XXXXX
		 *             +---+---+---+---+---+---+---+---+
		 *             | W | W | W | W | W | W | W | B |
		 *             +---+---+---+---+---+---+---+---+
		 *                                         XXXXX
		 *                                         XXXXX
		 * </pre>
		 *
		 * The ‘Average’ returned in this case will be 80, calculated
		 * as: (0+0+0+0+0+0+0+80)/1
		 * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
		 */
		int getAverage(void);

is displayed like this:

clang-format does not break the comments, so this is not the issue.

[ptillisch]

Hi @lmoellendorf. The contents of this "pop-up" (more officially referred to as the "editor hover") are provided by the clangd C++ language server.

Unfortunately the clangd developers weren't kind enough to provide formal documentation for how clangd formats this content so you have to hunt for little morsels of information here and there. In this case, the morsel is this commit message:

[clangd] Change line break behaviour for hoverinfo

Wether a line break is hard or soft is determined by the following rules (some of which have been discussed in clangd/clangd#95): Line breaks that are preceded by a punctuation are retained Line breaks that are followed by "interesting characters" (e.g. Markdown syntax, doxygen commands) are retained All other line breaks are removed

[lmoellendorf]

Thanks for your fast reply!

I tried to fix the line breaks using punctuation at the end of lines:

		 *
		 * <pre>
		 *                             XXXXX                         .
		 *                             XXXXX                         .
		 *             +---+---+---+---+---+---+---+---+             .
		 *             | W | W | W | W | B | W | W | W |             .
		 *             +---+---+---+---+---+---+---+---+             .
		 *                             XXXXX                         .
		 *                             XXXXX                         .
		 * </pre>
		 *

Next I tried to fix the formatting using dots instead of whitespaces:

		 *
		 * <pre>.......................XXXXX..........................
		 *.............................XXXXX..........................
		 *.............+---+---+---+---+---+---+---+---+..............
		 *.............| W | W | W | W | B | W | W | W |..............
		 *.............+---+---+---+---+---+---+---+---+..............
		 *.............................XXXXX..........................
		 *.............................XXXXX..........................
		 * </pre>
		 *

Actually what is needed is something like <pre></pre> in doxygen and others, which leaves the enclosed section unformatted with monospace font.

[ptillisch]

I've also been disappointed by the Editor Hover's lack of markup support. From what I can see, the only markup it recognizes is wrapping line content in backticks for inline preformatted.

I saw that Microsoft did finally add it just recently in their C++ language support VS Code extension:

Markdown comment support for tooltip display of hover

Arduino IDE doesn't use that extension, but maybe this will at least start to establish a convention of using Markdown in C++ doc comments and expecting that the consuming applications will render that markup.