Javadoc Preview Ignores paragraph separators

[Johnco3]

Javadoc Preview broken. 

The following example ignores the paragrapgh breaks.  (note the terminating </p> is not required in Javadoc (it doesn't fix it either).  This currently works in SlickEdit Pro 2022.

Note, another difference is the blank line separator before the Parameters: section (I think I prefer this in the new beta, SlickEdit 2022 leaves no space before the parameters section which looks a little ugly in my opinion).

Code: [Select]

    /**
     * configureDevice slot.
     *
     * <p>This slot runs in the worker thread context.
     *
     * <p>If <code>rDeviceConfigPath</code> is in XML format (*.xml
     * or *.adcx), it is parsed for the the input and output
     * VL definitions and converted to ASCII-HEX format where the
     * file is used to initialize the AIT hardware.
     *
     * <p>If <code>rDeviceConfigPath</code> is in ASCII-HEX format
     * (*.hex or *.adc), the file is converted to XML and parsed for
     * input and output VL definitions.  The ASCII-HEX file is then
     * used to initialize the AIT hardware.
     *
     * <p>If the <code>rDeviceConfigPath</code> is located in the
     * resource area of the application, we must firstly copy the
     * file to the temp folder so it can read by the converter
     * executable.  The code uses the <code>QTemporaryFile</code>
     * for this purpose.
     *
     * @param rDeviceConfigPath [in] XML or HEX Simulyzer device
     *                          configuration path (filesystem or
     *                          resource file).
     */
    void handleConfigureDevice(const QFileInfo& rDeviceConfigPath);

I attach a copy of the latest version of the preview (as of Beta 3, it was also broken in Beta 2) and the previous working version

[Dennis]

Actually, the paragraph separators are not being ignored.  I adjusted the style sheet to make the paragraph break smaller so it is possible to read more text within the comment.  Maybe I made it too small.

[Johnco3]

Yes definitely too small.  Also I like the new spacing above the parameter section.  One thing that would be a nice to have would be the alignment of the [in]/[out]/[in/out] types.  After the monospaced variable name add sufficient spaces to align the - [in]/[out]/[in/out] types, wrapping lines around at the opening [ - like you do in the header.

[Dennis]

That's a fair suggestion, however, I'm not sure that is standard Javadoc/Doxygen.  I see this for Doxygen.  https://www.doxygen.nl/manual/commands.html#cmdparam   We do handle that style.

[Dennis]

I put in a tweak to handle [in], [out], [in,out] (along with several other specific words that are useful in this context) appearing before the comment text, but formatting it as if it used the standard Doxygen style annotation.  Here is a sample.  I'm not certain that matches what you described.

[Johnco3]

Dennis, I tried the support for @param[in] for example and with no spaces between the param and the oppening square bracket, the color coding for the param is lost.  I've always put the [in,out], [in], [out] at the same indentation level as the first comment for the parameter - perhaps I was incorrect and I'm not sure that the doxygen guidelines correctly.   I am not sure that the spec is very accurate, as it seems to specify a space between the param and the opening '[', which does not match their example (if their example used this space the color coding to the '@param' text would not be broken).
Also the doxygen example for 'dir' is well formatted, as a comment header (it is missing the closing comment '*/').

Code: [Select]

/*!
   Copies bytes from a source memory area to a destination memory area,
   where both areas may not overlap.
   @param[out] dest The memory area to copy to.
   @param[in]  src  The memory area to copy from.
   @param[in]  n    The number of bytes to copy
  /
void memcpy(void *dest, const void *src, size_t n);

With this example (fixed up with the missing */) The latest beta 3 shows the attached screen shot, which is definitely not very useful.

As far as something that would look awesome in the preview area, I think aligning the '-' separators on the same column for each parameter would look amazing.  Naturally line wrap would need to be indented 2 spaces after the leading - to make things look good.  Alternative food for thought might be to consider using a separate color for the [in,out,reference etc.]

[Dennis]

I added some code to align the comment descriptions.  However, it just takes a guess at how much space to allow, so if there is a particularly long named parameter, it's going to free flow.

[Johnco3]

Nice, I look forward to seeing how it looks.

[Dennis]

Here is a sample: