Simple documentation question

General Usage
1

Hi,
this is quite dumb :frowning: I’m trying to document a function that is called

CD_k_CUDA

and I want to document it. I write a doc string like

"""
CD_k_CUDA(x,W) 
...
"""
function CD_k_CUDA(x,W)

but when i try to do
?CD_k_CUDA
the underscore _ signs do not appear, and k shows up in italic. How would you make the two _ appear ?

Thanks a lot,

Ferran.

1 Like
2

Indent the line that bears the name of the function, such that the Markdown parser takes it as a line of code:

"""
    CD_k_CUDA(x,W) 
...
"""
function CD_k_CUDA(x,W)

More recommendations about how to write the docstrings here:
https://docs.julialang.org/en/v1/manual/documentation/index.html

Also, as a matter of style: normally function names are not written with capital letters.

7 Likes
3

Thaks, I’ll try that.
Regarding styles, beauty is in the eye of the beholder. I don’t like the Julia standards :slight_smile:
Best,
Ferran.

4

The other option is to do:

CD\_k\_CUDA(x,W)

The slash will keep the underscores from identifying as italics.

5

While I agree on the fact that beauty is in the eye of the beholder and also have some criticism of the Julia style guide, I yet think you are a little confused. A style guide is (almost) never created because someone is trying to impose some notion of beauty. They are created for consistency and because some conventions have value if everyone follow them and some conventions have inherent value/utility.

5 Likes
6

That’s not right. Writing CD\_k\_CUDA(x,W) in the docstring yields:

ERROR: LoadError: syntax: invalid escape sequence
1 Like
7

:-/ okay try two slashes:

CD\\_k\\_CUDA(x,W)

How annoying…

1 Like
8

You probably do want it to end up formatted like code, though. In places where you don’t indent by 4 spaces or have larger code blocks fenced with ```s, I’d use inline markdown backticks: `CD_k_CUDA(x,W)`.

3 Likes