disallow extra lines between a docstring and the documented object, special parsing for @doc

[JeffBezanson]

I think this rule makes sense; it would be pretty confusing if a string still acted as a doc string despite any number of intervening blank and comment lines.

@Keno @yuyichao In addition to this, I'd consider restricting doc string parsing to basic string literals. For any other kind of string you'd have to use @doc xyz""" """ -> .... That syntax is ugly but the parsing rule is equally simple. Thoughts?

[yuyichao]

I'd consider restricting doc string parsing to basic string literals. For any other kind of string you'd have to use @doc xyz""" """ -> .... That syntax is ugly but the parsing rule is equally simple. Thoughts?

Isn't that what was there before? IIRC the decision at the time was that we should allow arbitrary string macros for docstring with @doc but should encourage a single default one (markdown) by only supporting that as the one that can be used without @doc. I think this still makes sense though I don't have a preference.

[JeffBezanson]

Before there was also a special case allowing doc""" """.

[JeffBezanson]

This is not fully resolved yet, but here are a couple options from triage:

1. Only doc" " is parsed as a doc string (in addition to normal string literals, as before), but use a suffix to specify the format:

doc"""
    text text text
"""latex
f(x) = x

The doc_str macro would convert its argument to a call to latex_str instead, based on the suffix.

2. Use a naming convention, e.g. any string macro ending in doc is parsed as a doc string:

latexdoc"""
"""
f(x) = x

3. Allow all string literals as doc strings, and use _cmd macros for things like Cxx instead (cxx``` ... ``` ).

4. Have some way to register that a certain string macro is or isn't valid as a doc string, in order to give a clear error message when something unintentionally becomes a doc string.

5. Only allow normal string literals as doc strings, and use @doc for everything else. The main problem is that the full syntax is pretty ugly:

@doc latex"""
""" ->
f(x) = x

That could potentially be fixed by giving @doc special parsing to at least allow removing the ->. That's not so bad since @doc is built in, unlike doc" ".

[JeffBezanson]

I'm kind of leaning towards option 5 --- if we're willing to give doc" " special parsing, we might as well give @doc special parsing instead, since it's more general. You can use @doc <anything> to use any expression as a doc string.

[StefanKarpinski]

I like option 5 as well. What would the parsing rule be? If @doc is called with only a single expression, then consume the following expression in the manner of doc strings as well?

[JeffBezanson]

Yes, I think that's it.

[JeffBezanson]

OK, implemented! I also deprecated all the things:

• deprecation warning for multiple lines between docstring and object
• special parsing of doc" " is deprecated
• using -> in @doc calls is deprecated