Proposal: disable doctests per doc entry

[eksperimental]

Hi list,
documenting functions made me realize the need to be able to disable
doctests per documentation entry. So I would like to propose the
addition of support for:

`@doc doctest: false`
`@moduledoc doctest: false`
`@typedoc doctest: false`

(In the same fashion as we declare guards with `@doc guard: true`)

To indicate and to disable doctests for the given documentation entry
within the module being defined.

While currenty this can be done from the test file, passing the :exclude
or :only options to `doctest`, I find it inconvenient to define what
gets doctested in another file and have to switch back and forth to make
sure of this.
I would like to focus on my module and know whether I can write invalid
doc tests or not.


Please let me know what you thing about this,
- Eksperimental

[Eric Meadows-Jönsson]

I don't think this is needed since if you don't want to use doctests you don't have to use the doctest syntax.

For example, instead of:

iex> 1 + 1
2

you can do:

> 1 + 1
2

[eksperimental]

That's a nice trick Eric.
I didn't now about it, it formats well in ExDoc, with the exception that
">" is not hightlighted and it is selectable., but I can create a
feature request for MakeUp.

So far the only way I knew to disable it is not to use `iex>`
altogether.

Thank you

[Wojtek Mach]

Another popular pattern I've seen in the wild is:

## Examples

    Foo.bar()
    #=> :baz

since :baz is in a comment, it is not going to be syntax highlighted, but I think that's fine.

-- 
You received this message because you are subscribed to the Google Groups "elixir-lang-core" group.
To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-co...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/61b21664.1c69fb81.f6a30.02cfSMTPIN_ADDED_MISSING%40gmr-mx.google.com.

[eksperimental]

That is pretty much what I was using (it is what we use in Elixir core
when an exception is raised),
the issue with that is the it does not play out well with multi-line
return values, which was my use case, and therefore this proposal.

On Fri, 10 Dec 2021 14:42:51 +0100
Wojtek Mach <woj...@wojtekmach.pl> wrote:

> Another popular pattern I've seen in the wild is:
>
> ## Examples Foo.bar() #=> :baz
>
> since :baz is in a comment, it is not going to be syntax highlighted,
> but I think that's fine.
>

> On December 9, 2021, elixir-lang-core <elixir-lang-