Document REPL behavior of underscore in docstrings

[nandoconde]

Motivation

Although it is consistent, it should be documented that an underscore does not behave equally across all parts of docstrings.

Behavior 1 - Method signature and block codes: here it works as an underscore.

Behavior 2 - Usual text: here it works as a modifier for underlining the whole text. If not closed by a second underscore, it can even prevent block codes (see Example 2). In order to write an underscore, it must be double-escaped (Example 3), because escaping produces errors (Example 4)

Example 1 (correct)

"""
   my_fun(x, y, z)

Perform _sumation_ of elements. The following holds: `x + y + z == my_fun(x, y, z)`
"""
function my_fun(x,y,z)
   return x+y+z
end

Example 2 (undesired behavior)

"""
   my_fun(x, y, z)

Perform _sumation_ of elements_. The following holds: `x + y + z == my_fun(x, y, z)`
"""
function my_fun(x,y,z)
   return x+y+z
end

Example 3 (correctly escaped)

"""
   my_fun(x, y, z)

Perform _sumation_ of elements\\_. The following holds: `x + y + z == my_fun(x, y, z)`
"""
function my_fun(x,y,z)
   return x+y+z
end

Example 4 (error by escaping character)

"""
   my_fun(x, y, z)

Perform _sumation_ of elements\_. The following holds: `x + y + z == my_fun(x, y, z)`
"""
function my_fun(x,y,z)
   return x+y+z
end

(prueba.jl is a file with a single module that exports my_fun)

I can write a documentation PR if consensus is reached.

[Seelengrab]

Example 4 (error by escaping character)

The error occurs before parsing of the docstring into documentation:

julia> """                            
          example multiline string    

       This is \_ wrong.              
       """                            
ERROR: syntax: invalid escape sequence
Stacktrace:                           
 [1] top-level scope                  
   @ none:1                           

\_ is not a valid escape sequence for strings and in order to pass the escaping of _ onto the markdown parser in the background, \ itself has to be escaped.

[nandoconde]

Thanks, I had kind of figured that out. I was rather pointing at the fact that this should all be documented, even if it is correct everything.

[Seelengrab]

At least the part about invalid escape sequence is documented, under the section of Strings. In that regard, docstrings are not differently parsed from other kinds of multiline strings:

Julia fully supports Unicode characters and strings. As discussed above, in character literals, Unicode code points can be represented using Unicode \u and \U escape sequences, as well as all the standard C escape sequences. These can likewise be used to write string literals

The documentation about docstrings itself mentions that "any object can be associated with any other as metadata", where strings are by default interpreted as markdown.

The bad result in example 2 may be an issue of the markdown parser being too greedy in the Markdown stdlib though. Preferring code blocks over highlighting may be better.