Where can I find Erlang-specific details on the possible return types for Mnesia:create_table?

Questions / Help
,
1

Trying to get details on the possible return types for Mnesia:create_table.
Erlang docs are basically absent: Erlang -- mnesia

Elixir docs actually have the answer that I’m looking for! Mnesia · Elixir School

Am I missing some other authoritative Erlang documentation somewhere??? Are we supposed to just go look at the Mnesia source code?

I’ve recently returned to Erlang development and am training my team and a client’s team on it. My recollection was that the documentation for return specs was more complete back then (10+ years ago). Is that just a false memory?

2

I am not sure what is missing in the Erlang docs. Click on t_result and you see the result tuples that the function returns. So no need to read the mnesia code to read that.

If something can be improved I guess a they are happy to get a PR.

3

Here’s what that says: t_result(Res) = {atomic, Res} | {aborted, Reason :: term()}

So it’s a type spec of sorts but zero semantics. For example, I want to know what happens with I call create_table when the table already exists. That’s not discoverable in this documentation but it’s spelled out explicitly in the Elixir docs on Mnesia. I’d say that’s incomplete.

4

It’s not specific to create_table, but there’s a list here:

https://www.erlang.org/doc/man/mnesia.html#error_description-1

3 Likes
5

That’s a bit better… should be linked more directly from the create_table api docs. But yeah - this is like trying to learn a language by reading the iso standards doc. Not a useful method of introducing people who want to use it to the system.

1 Like
6

Look at the documentation for mnesia:error_description, there you will find what you are looking for. Of course things can be improved, but I think this is quite complete.

3 Likes
7

Thanks for the pointer. It definitely lists the possibilities but, without any context, it’s little more than a grammar reference. Completely inadequate, imho. That said, I am happy to contribute to improvements as I discover this stuff. Presumably the docs are in this repo: GitHub - erlang/erlang-org: The erlang.org website but I can’t actually find the content we’ve been discussing anywhere. Am I missing something?

8

The builtin application’s docs are in the erlang/otp repository, for
:mnesia.create_table specifically, you are probably looking for this:

3 Likes
9

Thanks - that was exactly what I was looking for. Hopefully we can submit some simple but useful improvements to these docs in the near term.

Beyond that - my hopes for better online Erlang docs go beyond what the current dtd files currently are designed to express. Probably the ideal example of best practices that I would hope we could aspire to is the remarkable cppreference website for ISO C++. Take a look at their page on the standard vector container: std::vector - cppreference.com

It has great docs on the interface, every parameter, and each return type & purpose succinctly together on a single page. Down further you have some internal implementation details. Even further is the coup-de-grace actual working sample code in a practical canonical use case!

I first encountered the combination of user/reference/example docs back in the late 90’s when PHP first came out and integrated with MySQL. Both those sites had great docs but they also allowed users to post short examples of using PHP functions in useful ways. Anyone with the smallest notion of coding could have those two websites up and teach themselves dynamic web page generation at a time when the language of the internet was perl and everything was sent out on a process per request CGI script. That’s what got PHP adopted.

The cppreference web page is a more complete and formal doc system which is enabled mostly due to the fantastic work and giant efforts of the iso standards committees. But it shows what can be done. I’m curious if the current Erlang docs infrastructure could be extended to support this kind of thing (I recall being able to do anything with xslt transformations in the late 90s but not sure I want to repeat that experience) or not.

Would be curious to hear others opinions on the value & effort for doing something like this for Erlang/OTP. I certainly think it would make the platform far more available to new developers and gain better adoption. Clearly the Elixir folk recognize this from their experience of excellent community due to Ruby’s creator, Matz’, efforts in that regard. That said - I adamantly want Erlang to do so without loosening its focus of being the top resilient and reliable technical project for distributed and actor-style concurrency. But even the most hardened tech curmudgeons I know who would love Erlang/OTP once it soaks into their mental model find the docs and tooling quite offputting. This is what I’m working to overcome as I move Erlang/OTP as a core technology in my company and that of our clients.

2 Likes