core: add documentation for RDF.Namespace and RDF.Vocabulary.Namespace

lib/rdf/datatype_ns.ex

@@ -7,6 +7,7 @@ defmodule RDF.Datatype.NS do
 
   use RDF.Vocabulary.Namespace
 
+  @vocabdoc false
   defvocab XSD,
     base_uri: "http://www.w3.org/2001/XMLSchema#",
     terms: ~w[

lib/rdf/namespace.ex

@@ -1,49 +1,30 @@
 defmodule RDF.Namespace do
   @moduledoc """
-  A `RDF.Namespace` is a module ...
+  A behaviour for resolvers of module atoms to URIs.
-
-  TODO: Rewrite this
-
-  A `RDF.Namespace` is a collection of URIs and serves as a namespace for its
-  elements, called terms. The terms can be accessed by qualification on the
-  resp. namespace module.
-
-  ## Using a `RDF.Namespace`
-
-  There are two types of terms in a `RDF.Namespace`, which are resolved
-  differently:
-
-  1. Lowercased terms (usually used for RDF properties, but this is not
-    enforced) are represented as functions on a Vocabulary module and return the
-    URI directly.
-  2. Capitalized terms are by standard Elixir semantics modules names, i.e.
-    atoms. In all places in RDF.ex, where an URI is expected, you can use atoms
-    qualified with a `RDF.Namespace` directly, but if you want to resolve it
-    manually, you can pass the `RDF.Namespace` qualified atom to `RDF.uri`.
-
-  Examples:
-
-      iex> RDF.NS.RDFS.subClassOf
-      %URI{authority: "www.w3.org", fragment: "subClassOf", host: "www.w3.org",
-       path: "/2000/01/rdf-schema", port: 80, query: nil, scheme: "http",
-       userinfo: nil}
-      iex> RDF.NS.RDFS.Class
-      RDF.NS.RDFS.Class
-      iex> RDF.uri(RDF.NS.RDFS.Class)
-      %URI{authority: "www.w3.org", fragment: "Class", host: "www.w3.org",
-       path: "/2000/01/rdf-schema", port: 80, query: nil, scheme: "http",
-       userinfo: nil}
-      iex> alias RDF.NS.RDFS
-      iex> RDF.triple(RDFS.Class, RDFS.subClassOf, RDFS.Resource)
-      {RDF.uri(RDFS.Class), RDF.uri(RDFS.subClassOf), RDF.uri(RDFS.Resource)}
 
+  Currently there's only one type of such namespaces: `RDF.Vocabulary.Namespace`,
+  but other types are thinkable and might be implemented in the future, eg.
+  namespaces for JSON-LD contexts.
   """
 
+  @doc """
+  Resolves a term to an URI.
+  """
   @callback __resolve_term__(atom) :: URI.t
 
+  @doc """
+  All terms of a `RDF.Namespace`.
+  """
   @callback __terms__() :: [atom]
 
 
+  @doc """
+  Resolves a qualified term to an URI.
+
+  It determines a `RDF.Namespace` from the qualifier of the given term and
+  delegates to remaining part of the term to `__resolve_term__/1` of this
+  determined namespace.
+  """
   def resolve_term(expr)
 
   def resolve_term(uri = %URI{}),

lib/rdf/ns.ex

@@ -1,4 +1,16 @@
 defmodule RDF.NS do
+  @moduledoc """
+  `RDF.Namespace`s for fundamental RDF vocabularies.
+
+  Namely:
+
+  - `RDF.NS.RDF`
+  - `RDF.NS.RDFS`
+  - `RDF.NS.OWL`
+  - `RDF.NS.SKOS`
+  - `RDF.NS.XSD`
+  """
+
   use RDF.Vocabulary.Namespace
 
   @vocabdoc """

lib/rdf/vocabulary_namespace.ex

@@ -1,43 +1,14 @@
 defmodule RDF.Vocabulary.Namespace do
   @moduledoc """
-  Defines a RDF Vocabulary as a `RDF.Namespace`.
+  A RDF vocabulary as a `RDF.Namespace`.
 
+  `RDF.Vocabulary.Namespace` modules represent a RDF vocabulary as a `RDF.Namespace`.
+  They can be defined with the `defvocab/2` macro of this module.
 
-  ## Strict vocabularies
+  RDF.ex comes with predefined modules for some fundamentals vocabularies in
-
+  the `RDF.NS` module.
-  What is a strict vocabulary and why should I use them over non-strict
+  Furthermore, the [rdf_vocab](https://hex.pm/packages/rdf_vocab) package
-  vocabularies and define all terms ...
+  contains predefined modules for popular vocabularies.
-
-
-  ## Defining a vocabulary
-
-  There are two basic ways to define a vocabulary:
-
-  1. You can define all terms manually.
-  2. You can load all terms from a specified namespace in a given dataset or
-     graph.
-
-  Either way, you'll first have to define a new module for your vocabulary:
-
-      defmodule Example do
-        use RDF.Vocabulary.Namespace
-
-        defvocab EX,
-          base_uri: "http://www.example.com/ns/",
-          terms: ~w[Foo bar]
-
-        # Your term definitions
-      end
-
-  The `base_uri` argument with the URI prefix of all the terms in the defined
-  vocabulary is required and expects a valid URI ending with either a `"/"` or
-  a `"#"`.
-
-
-  ## Reflection
-
-  `__base_uri__` and `__terms__` ...
-
   """
 
   @vocabs_dir "priv/vocabs"
@@ -59,7 +30,7 @@ defmodule RDF.Vocabulary.Namespace do
       case source!(opts) do
         {:terms, terms} -> {terms, nil}
         {:data, data}   -> {rdf_data_vocab_terms(data, base_uri), data}
-      end #|> IO.inspect()
+      end
 
     terms =
       terms
@@ -135,6 +106,7 @@ defmodule RDF.Vocabulary.Namespace do
     end
   end
 
+  @doc false
   defmacro define_vocab_terms(terms, base_uri) do
     terms
     |> Stream.map(fn
@@ -448,7 +420,7 @@ defmodule RDF.Vocabulary.Namespace do
   end
 
 
-  def filename!(opts) do
+  defp filename!(opts) do
     if filename = Keyword.get(opts, :file) do
       cond do
         File.exists?(filename) ->

test/unit/namespace_test.exs

@@ -1,7 +1,6 @@
 defmodule RDF.NamespaceTest do
   use ExUnit.Case
 
-  alias RDF.NS.RDFS
   doctest RDF.Namespace
 
 end