Thanks Devon, We already had long discussions about public vs private in the past and I don't want to rehash them here so I will just reiterate the main point: @doc and @moduledoc are about public APIs - if the documentation above is not meant to be read by anyone using your API, only those using the source code, then a code comment is the correct way to go.
As you said, some may not necessarily agree with this answer, but it is the answer we are sticking to. :) *José Valimwww.plataformatec.com.br <http://www.plataformatec.com.br/>Founder and Director of R&D* On Mon, Jan 29, 2018 at 9:58 AM, Devon Estes <devon.c.es...@gmail.com> wrote: > There has been lots of discussion around making things private (like > private modules, what to show in documentation for private functions that > aren't defined with defp, etc.). Currently there is an implicit rule that > if something is undocumented then it is private and shouldn't be used, so > we'll see `@doc false` or `@moduledoc false` indicating that this function > or module is private API. > > However, I think it would be helpful to be explicit about what is private > API by adding a `@private true` tag. This way there's no confusion between > a function that someone just forgot to document and what's private API. My > proposal is basically that all modules and functions that are defined with > `def` and `defmodule` are public by default. If someone would like to mark > the given function as private, they can add `@private true`. So, the > following code: > @doc false > def __build__(device, raw, line_or_bytes) do > %IO.Stream{device: device, raw: raw, line_or_bytes: line_or_bytes} > end > Would then become: > @doc """ Helpful documentation around what the function is used for to > make maintenance easier """ @private true > def __build__(device, raw, line_or_bytes) do > %IO.Stream{device: device, raw: raw, line_or_bytes: line_or_bytes} > end > > I see the benefits to this as: > > 1) Very explicit indication that something marked as private API is > private and can potentially change in a breaking fashion or disappear > entirely without deprecation in minor or patch releases. If users still use > those functions, that's totally on them if it's clearly marked as private. > 2) No longer confusing things that are accidentally undocumented with > things that are private. > 3) Encouraging more documentation of private API functions that other > maintainers of and contributors to a given library might find helpful. > 4) Adding this metadata could potentially lead to helpful tooling, like > displaying something with `IEx.Helpers.h/1` and clear indications of > private functions and modules in hexdocs. > 5) It should be relatively easy to implement since we're already storing > metadata chunks for things like @since and @deprecated. > > The drawbacks are potentially that this is just "one more thing" people > need to do when writing their code and to deal with in tooling. When the > EEP48 stuff is ready, I'm sure everyone will come clamoring with their > ideas for officially supported metadata to store in the BEAM file chunks. > Also, while it's technically non-breaking, once this chunk is implemented > there could be confusion around old code that still uses `@doc false` to > mark things as private until they update their code. So, it would require > some work from library maintainers (but it is trivially easy - essentially > one `sed` and you're done). > > However, given how much people seem to want some ability to clearly mark > things as private, I think this might be worth it, which is why I'm > proposing it 😀 > > I know I would like it, but I tend to prefer things that are explicit > rather than implicit. > > -- > 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-core+unsubscr...@googlegroups.com. > To view this discussion on the web visit https://groups.google.com/d/ > msgid/elixir-lang-core/e146e991-3c06-477a-a58f- > 44b04ff31960%40googlegroups.com > <https://groups.google.com/d/msgid/elixir-lang-core/e146e991-3c06-477a-a58f-44b04ff31960%40googlegroups.com?utm_medium=email&utm_source=footer> > . > For more options, visit https://groups.google.com/d/optout. > -- 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-core+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/CAGnRm4%2Bxmj_3DYb7ygKiS%3DAfUJLSY6Xpp1eHewNPJwjGZZCS0g%40mail.gmail.com. For more options, visit https://groups.google.com/d/optout.
