Line wrapping can break markdown JSDocs

[joheredi]

For example the table in this docsite: https://docs.microsoft.com/en-us/javascript/api/@azure/cognitiveservices-face/largefacelistoperations?view=azure-node-latest#addFaceFromStream_string__msRest_HttpRequestBody__Models_LargeFaceListAddFaceFromStreamOptionalParams_

Is broken because the MD table definition gets broken down into multiple lines which breaks MD.

Broken JSDoc:

   /**
     * * Different 'detectionModel' values can be provided. To use and compare different detection
     * models, please refer to [How to specify a detection
     * model](https://docs.microsoft.com/azure/cognitive-services/face/face-api-how-to-topics/specify-detection-model)
     * | Model | Recommended use-case(s) |
     * | ---------- | -------- |
     * | 'detection_01': | The default detection model for [Face -
     * Detect](https://docs.microsoft.com/rest/api/cognitiveservices/face/face/detectwithurl).
     * Recommend for near frontal face detection. For scenarios with exceptionally large angle
     * (head-pose) faces, occluded faces or wrong image orientation, the faces in such cases may not be
     * detected. |
     * | 'detection_02': | Detection model released in 2019 May with improved accuracy especially on
     * small, side and blurry faces. |
     */

Expected

   /**
     * * Different 'detectionModel' values can be provided. To use and compare different detection
     * models, please refer to [How to specify a detection
     * model](https://docs.microsoft.com/azure/cognitive-services/face/face-api-how-to-topics/specify-detection-model)
     * | Model | Recommended use-case(s) |
     * | ---------- | -------- |
     * | 'detection_01': | The default detection model for [Face - Detect] https://docs.microsoft.com/rest/api/cognitiveservices/face/face/detectwithurl). Recommend for near frontal face detection. For scenarios with exceptionally large angle (head-pose) faces, occluded faces or wrong image orientation, the faces in such cases may not be detected. |
     * | 'detection_02': | Detection model released in 2019 May with improved accuracy especially on small, side and blurry faces. |
     */

We have a few options

• Allow a flag to disable Line Wrapping or Allow setting a custom line width value
• Improve line wrapping to be smarter

[ramya-rao-a]

Allow a flag to disable Line Wrapping or Allow setting a custom line width value

This would apply to all content in the package right? How would a user make the decision to enable this flag? Will they need to review all of their generated docs to see what is broken and then opt-in?

Can we make this a default behavior and apply it to only when we see special content like tables? Also, am guessing this affects other languages too right?

[ramya-rao-a]

I guess what I am saying is that I vote for Option 2 which is to make line wrapping smarter and to check with other languages as to how they are solving this

cc @sarangan12

[joheredi]

@ramya-rao-a I agree!