How about using a colon at the end of a doc string? It would signifying that the string belongs to the object following and it is light on the eye.
This would look like: "Function documentation, blah": f(x) = 2x and """ A longer function documentation. - blah - blah """: f(x) = 2x (Also, maybe the syntax could require for the documented object to follow without an empty line.) On Sat, 2014-09-13 at 12:02, Rafael Fourquet <[email protected]> wrote: >> To me the only difference is that I > `> really don't want to write >> >> @doc """ >> commentary >> """ >> function ... >> >> >> whereas I already write things along the lines of >> >> # commentary >> function ... > > doc "function doc" > function ... > > is already better, and then let's get rid of even the doc keyword. It would > be kind of less breaking a change, as currently comments are mainly written > for developpers consumption and not meant for documenting public API and > would need to be fixed all at once. As both developper comments and API > documentation are needed, I find it useful to have two distincts means: > comments and strings. --
