Comments inside functions in scripts

[moyner]

Thanks for this great package - I use it extensively in my documentation and it has been a joy to use!

I have a question on the intended behavior for comments inside functions.

Let us say that I have the following script:

# # Header
function myfunc(x)
    # This is a comment
    return x^2
end

If I run Literate.markdown("ex.jl") the output of the code itself is as follows

# Header

```@example ex
function myfunc(x)
```

This is a comment

```@example ex
    return x^2
end
```

(I replaced backticks with ' to make it render correctly)

Unfortunately this breaks the function evaluation since the Documenter parsing of examples assumes that each bit is a executable bit of code. Is this intended behavior, or is it a bug? I like to make commented functions in my scripts, but I see that this is maybe not the most typical use of literate programming.

[fredrikekre]

(I replaced backticks with ' to make it render correctly)

You can use more backticks on the outer block, so if the code block uses 4 backticks you can use blocks within with three backticks (see my edit).

See https://fredrikekre.github.io/Literate.jl/v2/fileformat/#Syntax:

Since #-lines are treated as markdown we can not use that for regular julia comments, for this you can instead use ##, which will render as # in the output.

If I ever release Literate version 3 I think it would be smoother to requires the markdown-# to be the first character on the line.

[moyner]

Thanks! That makes sense - will use double comments in my helper functions 🙂