Decipher the Ecto.Schema.schema/2 macro

[toraritte]

According to the docs at https://hexdocs.pm/ecto/Ecto.Schema.html#schema/2 :

schema(source, list) View Source(macro) Defines a schema with a source name and field definitions.

After the guides and some toy projects it is clear that source refers to the corresponding table's name in the database, but it's strange why it's is not specified in the docs. Is it because (a) it should be obvious from the guides or (b) something else could also be passed here that covers an advanced use case.

So why not look at the source from the link above and take a look?

[toraritte]

Getting closer: https://hexdocs.pm/ecto/Ecto.Schema.html#belongs_to/3

Alternatively, because Ecto does not tie a schema to a given table, we can use separate tables for each association. Let’s start over and define a new Comment schema:

defmodule Comment do
  use Ecto.Schema

  schema "abstract table: comments" do
    # This will be used by associations on each "concrete" table
    field :assoc_id, :integer
  end
end

Where is abstract table (and probably others) mentioned? And why isn't it documented (or linked to) the schema/2 documentation?

How could be the schema/2 and belongs_to/3 docs made better? Because right now they are pretty abstruse. (See "Options" section of belongs_to/3 for example or what does the second parameter, queryable refer to?)