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 [email protected].
To view this discussion on the web visit
https://groups.google.com/d/msgid/elixir-lang-core/e146e991-3c06-477a-a58f-44b04ff31960%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
