Add documentation to RDF.Serialization, RDF.Reader, RDF.Decoder and RDF.Encoder

lib/rdf/reader.ex

@@ -1,15 +1,38 @@
 defmodule RDF.Reader do
+  @moduledoc """
+  General serialization-independent functions for reading a `RDF.Graph` or `RDF.Dataset` from a file or encoded-string.
+
+  You probably won't use these functions directly, but instead use the automatically
+  generated functions with same name on a `RDF.Serialization`, which implicitly
+  use the proper `RDF.Serialization.Decoder` module.
+  """
 
 
+  @doc """
+  Reads and decodes a serialized graph or dataset from a string.
 
+  It returns an `{:ok, data}` tuple, with `data` being the deserialized graph or
+  dataset, or `{:error, reason}` if an error occurs.
+  """
   def read_string(decoder, content, opts \\ []) do
     decoder.decode(content, opts)
   end
 
+  @doc """
+  Reads and decodes a serialized graph or dataset from a string.
+
+  As opposed to `read_string`, it raises an exception if an error occurs.
+  """
   def read_string!(decoder, content, opts \\ []) do
     decoder.decode!(content, opts)
   end
 
+  @doc """
+  Reads and decodes a serialized graph or dataset from a file.
+
+  It returns an `{:ok, data}` tuple, with `data` being the deserialized graph or
+  dataset, or `{:error, reason}` if an error occurs.
+  """
   def read_file(decoder, file, opts \\ []) do
     case File.read(file) do
       {:ok,   content} -> read_string(decoder, content, opts)
@@ -17,6 +40,11 @@ defmodule RDF.Reader do
     end
   end
 
+  @doc """
+  Reads and decodes a serialized graph or dataset from a file.
+
+  As opposed to `read_file`, it raises an exception if an error occurs.
+  """
   def read_file!(decoder, file, opts \\ []) do
     with content = File.read!(file) do
       read_string!(decoder, content, opts)

lib/rdf/serialization.ex

@@ -1,11 +1,59 @@
 defmodule RDF.Serialization do
+  @moduledoc """
+  A behaviour for RDF serialization formats.
 
+  A `RDF.Serialization` for a format can be implemented like this
+
+      defmodule SomeFormat do
+        use RDF.Serialization
+        import RDF.Sigils
+
+        @id           ~I<http://example.com/some_format>
+        @extension    "ext"
+        @content_type "application/some-format"
+      end
+
+  When `@id`, `@extension` and `@content_type` module attributes are defined the
+  resp. behaviour functions are generated automatically and return these values.
+
+  Then you'll have to do the main work by implementing a
+  `RDF.Serialization.Encoder` and a `RDF.Serialization.Decoder` for the format.
+
+  By default it is assumed that these are defined in `Encoder` and `Decoder`
+  moduler under the `RDF.Serialization` module of the format, i.e. in the example
+  above in `SomeFormat.Encoder` and `SomeFormat.Decoder`. If you want them in
+  another module, you'll have to override the `encoder/0` and/or `decoder/0`
+  functions in your `RDF.Serialization` module.
+  """
+
+  @doc """
+  An URI of the serialization format.
+  """
   @callback id :: URI.t
+
+  @doc """
+  The usual file extension for the serialization format.
+  """
   @callback extension :: binary
+
+  @doc """
+  The MIME type of the serialization format.
+  """
   @callback content_type :: binary
+
+  @doc """
+  A map with the supported options of the `Encoder` and `Decoder` for the serialization format.
+  """
   @callback options :: map
 
+  @doc """
+  The `RDF.Serialization.Decoder` module for the serialization format.
+  """
   @callback decoder :: module
+
+  @doc """
+  The `RDF.Serialization.Encoder` module for the serialization format.
+  """
   @callback encoder :: module
 
 

lib/rdf/serialization/decoder.ex

@@ -1,8 +1,26 @@
 defmodule RDF.Serialization.Decoder do
-  @moduledoc false
+  @moduledoc """
+  A behaviour for decoder of strings encoded in a specific `RDF.Serialization` format.
+  """
 
-  @callback decode(String.t, keyword) :: keyword(RDF.Graph)
-  @callback decode!(String.t, keyword) :: RDF.Graph
+
+  @doc """
+  Decodes a serialized `RDF.Graph` or `RDF.Dataset` from the given string.
+
+  It returns an `{:ok, data}` tuple, with `data` being the deserialized graph or
+  dataset, or `{:error, reason}` if an error occurs.
+  """
+  @callback decode(String.t, keyword) :: keyword(RDF.Graph.t | RDF.Dataset.t)
+
+  @doc """
+  Decodes a serialized `RDF.Graph` or `RDF.Dataset` from the given string.
+
+  As opposed to `decode`, it raises an exception if an error occurs.
+
+  Note: The `__using__` macro automatically provides an overridable default
+  implementation based on the non-bang `decode` function.
+  """
+  @callback decode!(String.t, keyword) :: RDF.Graph.t | RDF.Dataset.t
 
 
   defmacro __using__(_) do

lib/rdf/serialization/encoder.ex

@@ -1,8 +1,27 @@
 defmodule RDF.Serialization.Encoder do
-  @moduledoc false
+  @moduledoc """
+  A behaviour for encoders of `RDF.Graph`s or `RDF.Dataset`s in a specific
+  `RDF.Serialization` format.
+  """
 
-  @callback encode(RDF.Dataset, keyword) :: keyword(String.t)
-  @callback encode!(RDF.Dataset, keyword) :: String.t
+
+  @doc """
+  Encodes a `RDF.Graph` or `RDF.Dataset`.
+
+  It returns an `{:ok, string}` tuple, with `string` being the serialized
+  `RDF.Graph` or `RDF.Dataset`, or `{:error, reason}` if an error occurs.
+  """
+  @callback encode(RDF.Graph.t | RDF.Dataset.t, keyword) :: keyword(String.t)
+
+  @doc """
+  Encodes a `RDF.Graph` or `RDF.Dataset`.
+
+  As opposed to `encode`, it raises an exception if an error occurs.
+
+  Note: The `__using__` macro automatically provides an overridable default
+  implementation based on the non-bang `encode` function.
+  """
+  @callback encode!(RDF.Graph.t | RDF.Dataset.t, keyword) :: String.t
 
 
   defmacro __using__(_) do

lib/rdf/serializations/ntriples.ex

@@ -1,7 +1,7 @@
 defmodule RDF.NTriples do
   @moduledoc """
-  `RDF.NTriples` provides support for reading the N-Triples serialization
-  format.
+  `RDF.NTriples` provides support for reading and writing the N-Triples
+  serialization format.
 
   N-Triples is a line-based plain-text format for encoding an RDF graph.
   It is a very restricted, explicit and well-defined subset of both