PROPOSAL: add @private metadata chunk

[Devon Estes]

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.

[José Valim]

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é Valim

www.plataformatec.com.br

Founder and 

Director of R&D

--
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+unsubscribe@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.
For more options, visit https://groups.google.com/d/optout.