Issue with params with multi-line descriptions

[sfrenkiel]

Thanks for putting this tool together, it's been very useful for us. One small issue--

Params that have multiple lines of description result in bad markdown with your tool. Note the following class:

public class Test
{
    /**
     *
     * @param i single line description
     */
    public void method1(int i) {}

    /**
     *
     * @param i line1
     *          line2
     */
    public void method2(int i) {}
}

The markdown for method1 is good. In the markdown for method2, the word 'line2' comes before line1. This is a problem for us with params that have very long descriptions.

[ocram]

Thank you so much!

This should have been fixed in e1ea5a0 now :) Can you try, please?

[elifoster]

I just tested this, the result is:

Documentation

public void method1(int i)

• Parameters: i — single line description

public void method2(int i)

• Parameters: i — line1

  line2

I'm not certain that is exactly what should be expected. I believe it should result in:

Documentation

public void method1(int i)

• Parameters: i — single line description

public void method2(int i)

• Parameters: i — line1 line2

Or something similar.

[ocram]

@elifoster Thanks, that looks good! I understand that you might prefer another way of formatting the output, but your test proved that our fix to @sfrenkiel's original problem works correctly.

Personally, I prefer

line1

line2

to

line1 line2

for multi-line descriptions where the first version preserves the formatting from the source. You seem to disagree here, however. Do you have some example where your formatting makes more sense? Thank you!

[elifoster]

If the description happens to span multiple lines due to length, that is how it would be formatted in te source. Likewise with method descriptions and class descriptions which j2md already handles this way. That line break should be added for <br>s and line gaps.

For example

/**
 * @param a This method parameter is slightly complicated, and
 *         as such it spans multiple lines.
 */

would be expected to be a single line in the resulting markdown.

[ocram]

You're right, thanks!

What about the following way of formatting the output?

Becomes single-line description in Markdown:

/**
 * @param a This method parameter is slightly complicated, and
 *          as such it spans multiple lines.
 */

Becomes multi-line description in Markdown:

/**
 * @param a This method parameter is slightly complicated, and
 *
 *          as such it spans multiple lines.
 */

/**
 * @param a This method parameter is slightly complicated, and
 *          <br>
 *          as such it spans multiple lines.
 */

/**
 * @param a This method parameter is slightly complicated, and
 *          <p>
 *          as such it spans multiple lines.
 */

[elifoster]

Yes that would be more consistent.