improve docs

thiagomajesk · Apr 10, 2022 · 03c758f · 03c758f
1 parent d47c9c1
commit 03c758f
Show file tree

Hide file tree

Showing 6 changed files with 32 additions and 7 deletions.
diff --git a/lib/gluttony.ex b/lib/gluttony.ex
@@ -19,11 +19,16 @@ defmodule Gluttony do
 
     Parsing a xml string from a RSS feed:
 
-      {:ok, %{feed: feed, entries: entries}} = Gluttone.parse_string(xml)
+      {:ok, %{feed: feed, entries: entries}} = Gluttony.parse_string(xml)
 
     When a error happens, the reason is returned:
 
-      {:error, reason} = Gluttone.parse_string(xml)
+      {:error, reason} = Gluttony.parse_string(xml)
+
+    You can retrieve a common result interface by specifing the `raw` option as `false`.
+    This might be usefull to retrieve only relevant and common information, since RSS 2.0 and Atom 1.0 are very different specs:
+
+      {:ok, %Gluttony.Feed{}} = Gluttony.parse_string(xml, raw: false)
   """
   def parse_string(xml, opts \\ []), do: parse(xml, opts)
 

diff --git a/lib/gluttony/entry.ex b/lib/gluttony/entry.ex
@@ -1,5 +1,7 @@
 defmodule Gluttony.Entry do
-  @moduledoc false
+  @moduledoc """
+  Defines a common entry interface for RSS 2.0 and Atom 1.0 feeds.
+  """
 
   @type t :: __MODULE__
 

diff --git a/lib/gluttony/feed.ex b/lib/gluttony/feed.ex
@@ -1,5 +1,7 @@
 defmodule Gluttony.Feed do
-  @moduledoc false
+  @moduledoc """
+  Defines a common channel interface for RSS 2.0 and Atom 1.0 feeds.
+  """
 
   @type t :: __MODULE__
 

diff --git a/lib/gluttony/fetchers/favicon.ex b/lib/gluttony/fetchers/favicon.ex
@@ -1,4 +1,9 @@
 defmodule Gluttony.Fetchers.Favicon do
+  @moduledoc """
+  Retrieves icons available in the given URL.
+  Exposes the same functions as `HTTPoison`.
+  """
+
   use HTTPoison.Base
 
   def process_response_body(body) do

diff --git a/lib/gluttony/fetchers/opengraph.ex b/lib/gluttony/fetchers/opengraph.ex
@@ -1,4 +1,9 @@
 defmodule Gluttony.Fetchers.Opengraph do
+  @moduledoc """
+  Retrieves opengraph information available in the given URL.
+  Exposes the same functions as `HTTPoison`.
+  """
+
   use HTTPoison.Base
 
   @tags ~w(

diff --git a/lib/gluttony/unfurler.ex b/lib/gluttony/unfurler.ex
@@ -1,13 +1,19 @@
 defmodule Gluttony.Unfurler do
   @moduledoc """
   Enriches feed data by unfurling available urls.
-
-  For feeds, it returns favicons and images available in the URL.
-  FOr entries, it returns the available opengraph information on the page.
+  Uses `Gluttony.Fetchers.Favicon` and `Gluttony.Fetchers.Opengraph` internally.
   """
 
   alias Gluttony.{Feed, Entry}
 
+  @doc """
+  Accepts a `Gluttony.Feed` or `Gluttony.Entry` struct and retrieves data from the url.
+
+  For `Feed`, it returns favicons and images available in the given URL.
+  For `Entry`, it returns available opengraph information on the page.
+  """
+  def unfurl(term)
+
   def unfurl(%Feed{url: nil}), do: nil
 
   def unfurl(%Feed{url: url}) do