--EOL option does not properly handle @example tag line endings

[kevlon85]

As explained in #92, when generating markdown from JS files with CRLF line endings the output is produced with mixed line endings.

As is the recommended fix for that issue I tried using the new --EOL option to force the output to use consistent line endings. However this option does not seem to be fully working as expected.

When I run jsdoc2md test.js --EOL win32 > README.md over the following code saved with CRLF line endings:

/**
 * Adds two numbers.
 * @param {number} a The first number to be added.
 * @param {number} b The second number to be added.
 * @returns {number} The sum of a and b.
 * @example
 * let a = 1;
 * let b = 2;
 * // returns 3
 * add(a, b);
 */
function add(a, b) {
    return a + b;
}

it correctly outputs the line endings for everything except multiline @example tags where it instead outputs just carriage returns.

The same thing happens when running with option --EOL posix.

jsdoc2md test.js --EOL posix > README.md:

These same commands generate the expected output (completely consistent line encodings) when the input file is saved using LF line encodings.

This causes problems as not all markdown renderers render a carriage return on its own as a new line which means the examples get squashed onto one line.

I am using jsdoc-to-markdown version 9.0.1 and dmd version 7.0.6 on Windows 11.

Let me know if you are unable to reproduce this or if there is any more information I can provide.

[75lb]

Hi, thanks for the report.. I had a look..

I created a file with the code you posted plus CRLF line-endings.. Here is the file inspected using node's util.inspect(fileContent) (all CRLFs as required for this reproduction case):

'/**\r\n' +
  ' * Adds two numbers.\r\n' +
  ' * @param {number} a The first number to be added.\r\n' +
  ' * @param {number} b The second number to be added.\r\n' +
  ' * @returns {number} The sum of a and b.\r\n' +
  ' * @example\r\n' +
  ' * let a = 1;\r\n' +
  ' * let b = 2;\r\n' +
  ' * // returns 3\r\n' +
  ' * add(a, b);\r\n' +
  ' */\r\n' +
  'function add(a, b) {\r\n' +
  '    return a + b;\r\n' +
  '}\r\n'

Running jsdoc2md --EOL win32 example.js against the above input code produces this markdown:

'<a name="add"></a>\r\n' +
  '\r\n' +
  '## add(a, b) ⇒ <code>number</code>\r\n' +
  'Adds two numbers.\r\n' +
  '\r\n' +
  '**Kind**: global function  \r\n' +
  '**Returns**: <code>number</code> - The sum of a and b.  \r\n' +
  '\r\n' +
  '| Param | Type | Description |\r\n' +
  '| --- | --- | --- |\r\n' +
  '| a | <code>number</code> | The first number to be added. |\r\n' +
  '| b | <code>number</code> | The second number to be added. |\r\n' +
  '\r\n' +
  '**Example**  \r\n' +
  '```js\r\n' +
  'let a = 1;\rlet b = 2;\r// returns 3\radd(a, b);\r\n' +
  '```\r\n'

Running the same command again, but with --EOL posix produces this output:

'<a name="add"></a>\n' +
  '\n' +
  '## add(a, b) ⇒ <code>number</code>\n' +
  'Adds two numbers.\n' +
  '\n' +
  '**Kind**: global function  \n' +
  '**Returns**: <code>number</code> - The sum of a and b.  \n' +
  '\n' +
  '| Param | Type | Description |\n' +
  '| --- | --- | --- |\n' +
  '| a | <code>number</code> | The first number to be added. |\n' +
  '| b | <code>number</code> | The second number to be added. |\n' +
  '\n' +
  '**Example**  \n' +
  '```js\n' +
  'let a = 1;\rlet b = 2;\r// returns 3\radd(a, b);\n' +
  '```\n'

I see the issue and it is on this line:

  'let a = 1;\rlet b = 2;\r// returns 3\radd(a, b);\n' +

There are three naked \r characters. This matches your screenshots. This character should only be either \r\n or \n, nothing else. Bug - thanks for letting me know.

[75lb]

I've traced this issue back to jsdoc.. If you run jsdoc2md --jsdoc example.js against your example code, you can see the naked \r characters in the output:

"examples": [
  "let a = 1;\rlet b = 2;\r// returns 3\radd(a, b);"
],

Since there hasn't been a significant jsdoc release for almost 10 years, I might need fix this with a workaround..

[75lb]

Fixed and released in jsdoc2md v9.0.2 - let me know if there's anything else 👍

[kevlon85]

Looks good to me! Thanks for the quick fix!