Misc doc changes

Besides other documentation changes, this commit ensures the generated HTML doc for HexDocs.pm will become the main reference doc for this Elixir library which leverage on latest features of ExDoc.
otobus · Dec 26, 2021 · be0a875 · be0a875
1 parent 4981654
commit be0a875
Show file tree

Hide file tree

Showing 12 changed files with 100 additions and 72 deletions.
diff --git a/.formatter.exs b/.formatter.exs
@@ -1,4 +1,5 @@
+# Used by "mix format"
 [
-  inputs: ["mix.exs", "{config,lib,test}/**/*.{ex,exs}"],
+  inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}"],
   line_length: 80
 ]
diff --git a/.gitignore b/.gitignore
@@ -1,14 +1,14 @@
 # The directory Mix will write compiled artifacts to.
-/_build
+/_build/
 
 # If you run "mix test --cover", coverage assets end up here.
-/cover
+/cover/
 
 # The directory Mix downloads your dependencies sources to.
-/deps
+/deps/
 
-# Where 3rd-party dependencies like ExDoc output generated docs.
-/doc
+# Where third-party dependencies like ExDoc output generated docs.
+/doc/
 
 # Ignore .fetch files in case you like to edit your project deps locally.
 /.fetch
@@ -19,4 +19,11 @@ erl_crash.dump
 # Also ignore archive artifacts (built via "mix archive.build").
 *.ez
 
-.DS_Store
+# Ignore package tarball (built via "mix hex.build").
+event_bus-*.tar
+
+# Temporary files for e.g. tests.
+/tmp/
+
+# Misc.
+.DS_Store
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,7 +4,7 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
-## [1.6.X]
+## [1.6.X] 2020-01-20
 
 - Update type names and docs for consistent naming convention (Note: there is no logic or method name change)
 - Update the Travis script to prevent breaks on merges:

diff --git a/LICENSE → LICENSE.md b/LICENSE → LICENSE.md
@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2019 Mustafa Turan
+Copyright (c) 2017 Mustafa Turan
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

diff --git a/README.md b/README.md
@@ -1,9 +1,11 @@
 # EventBus
 
 [![Build Status](https://travis-ci.org/otobus/event_bus.svg?branch=master)](https://travis-ci.org/otobus/event_bus)
-[![Hex.pm](https://img.shields.io/hexpm/v/event_bus.svg)](http://hex.pm/packages/event_bus)
-[![Hex.pm](https://img.shields.io/hexpm/dt/event_bus.svg)](https://hex.pm/packages/event_bus)
-[![Hex.pm](https://img.shields.io/hexpm/dw/event_bus.svg)](https://hex.pm/packages/event_bus)
+[![Module Version](https://img.shields.io/hexpm/v/event_bus.svg)](https://hex.pm/packages/event_bus)
+[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/event_bus/)
+[![Total Download](https://img.shields.io/hexpm/dt/event_bus.svg)](https://hex.pm/packages/event_bus)
+[![License](https://img.shields.io/hexpm/l/event_bus.svg)](https://github.com/otobus/event_bus/blob/master/LICENSE)
+[![Last Updated](https://img.shields.io/github/last-commit/otobus/event_bus.svg)](https://github.com/otobus/event_bus/commits/master)
 
 Traceable, extendable and minimalist event bus implementation for Elixir with built-in event store and event watcher based on ETS.
 
@@ -63,13 +65,13 @@ Traceable, extendable and minimalist event bus implementation for Elixir with bu
 
 [Wiki](https://github.com/otobus/event_bus/wiki)
 
-[Contributing](https://github.com/otobus/event_bus/blob/master/CONTRIBUTING.md)
+[Contributing](./CONTRIBUTING.md)
 
-[License](https://github.com/otobus/event_bus/blob/master/LICENSE)
+[License](./LICENSE.md)
 
-[Code of Conduct](https://github.com/otobus/event_bus/blob/master/CODE_OF_CONDUCT.md)
+[Code of Conduct](./CODE_OF_CONDUCT.md)
 
-[Questions](https://github.com/otobus/event_bus/blob/master/QUESTIONS.md)
+[Questions](./QUESTIONS.md)
 
 ## Features
 
@@ -101,11 +103,13 @@ Start using `event_bus` library in five basic steps:
 
 ## Installation
 
-The package can be installed by adding `event_bus` to your list of dependencies in `mix.exs`:
+The package can be installed by adding `:event_bus` to your list of dependencies in `mix.exs`:
 
 ```elixir
 def deps do
-  [{:event_bus, "~> 1.6.2"}]
+  [
+    {:event_bus, "~> 1.6.2"}
+  ]
 end
 ```
 
@@ -210,7 +214,7 @@ Optional, but good to have field for all events to track when the event generato
 
 **`occurred_at` attribute**
 
-Optional, but good to have field for all events to track when the event occurred with unixtimestamp value. The library does not automatically set this value since the value depends on the timing choice.
+Optional, but good to have field for all events to track when the event occurred with unix timestamp value. The library does not automatically set this value since the value depends on the timing choice.
 
 **`ttl` attribute**
 
@@ -507,7 +511,7 @@ This feature removed with the version 1.3 to keep the core library simple. If yo
 
 ### EventBus.Metrics Library
 
-EventBus has some addons to extend its optional functionalities. One of them is `event_bus_metrics` library which comes with a UI, RESTFul endpoints and SSE streams to provide instant metrics for event_bus topics.
+EventBus has some addons to extend its optional functionalities. One of them is `event_bus_metrics` library which comes with a UI, RESTful endpoints and SSE streams to provide instant metrics for event_bus topics.
 
 [EventBus.Metrics Instructions](https://github.com/otobus/event_bus/wiki/EventBus-Metrics-and-UI)
 
@@ -531,11 +535,11 @@ A few sample addons listed below. Please do not hesitate to add your own addon t
 
 Note: The addons under [https://github.com/otobus](https://github.com/otobus) organization implemented as a sample, but feel free to use them in your project with respecting their licenses.
 
-## License
+## Copyright and License
 
 MIT
 
-Copyright (c) 2019 Mustafa Turan
+Copyright (c) 2017 Mustafa Turan
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

diff --git a/lib/event_bus.ex b/lib/event_bus.ex
@@ -1,7 +1,7 @@
 defmodule EventBus do
   @moduledoc """
   Traceable, extendable and minimalist event bus implementation for Elixir with
-  built-in event store and event observation manager based on ETS
+  built-in event store and event observation manager based on ETS.
   """
 
   alias EventBus.Manager.{
@@ -65,7 +65,7 @@ defmodule EventBus do
   @type topic_patterns :: list(topic_pattern())
 
   @doc """
-  Send an event to all subscribers
+  Send an event to all subscribers.
 
   ## Examples
 
@@ -81,7 +81,7 @@ defmodule EventBus do
     as: :notify
 
   @doc """
-  Check if a topic registered
+  Check if a topic registered.
 
   ## Examples
 
@@ -95,20 +95,21 @@ defmodule EventBus do
     as: :exist?
 
   @doc """
-  List all the registered topics
+  List all the registered topics.
 
   ## Examples
 
       EventBus.topics()
       [:metrics_summed]
+
   """
   @spec topics() :: topics()
   defdelegate topics,
     to: Topic,
     as: :all
 
   @doc """
-  Register a topic
+  Register a topic.
 
   ## Examples
 
@@ -122,7 +123,7 @@ defmodule EventBus do
     as: :register
 
   @doc """
-  Unregister a topic
+  Unregister a topic.
 
   ## Examples
 
@@ -136,7 +137,7 @@ defmodule EventBus do
     as: :unregister
 
   @doc """
-  Subscribe a subscriber to the event bus
+  Subscribe a subscriber to the event bus.
 
   ## Examples
 
@@ -155,7 +156,7 @@ defmodule EventBus do
     as: :subscribe
 
   @doc """
-  Unsubscribe a subscriber from the event bus
+  Unsubscribe a subscriber from the event bus.
 
   ## Examples
 
@@ -175,7 +176,7 @@ defmodule EventBus do
 
   @doc """
   Check if the given subscriber subscribed to the event bus for the given topic
-  patterns
+  patterns.
 
   ## Examples
 
@@ -198,7 +199,7 @@ defmodule EventBus do
     as: :subscribed?
 
   @doc """
-  List the subscribers
+  List the subscribers.
 
   ## Examples
 
@@ -216,7 +217,7 @@ defmodule EventBus do
     as: :subscribers
 
   @doc """
-  List the subscribers for the given topic
+  List the subscribers for the given topic.
 
   ## Examples
 
@@ -234,7 +235,7 @@ defmodule EventBus do
     as: :subscribers
 
   @doc """
-  Fetch an event
+  Fetch an event.
 
   ## Examples
 
@@ -248,7 +249,7 @@ defmodule EventBus do
     as: :fetch
 
   @doc """
-  Fetch an event's data
+  Fetch an event's data.
 
   ## Examples
 
@@ -261,9 +262,10 @@ defmodule EventBus do
     as: :fetch_data
 
   @doc """
-  Mark the event as completed for the subscriber
+  Mark the event as completed for the subscriber.
 
   ## Examples
+
       topic        = :hello_received
       event_id     = "124"
       event_shadow = {topic, event_id}
@@ -285,7 +287,7 @@ defmodule EventBus do
     as: :mark_as_completed
 
   @doc """
-  Mark the event as skipped for the subscriber
+  Mark the event as skipped for the subscriber.
 
   ## Examples
 

diff --git a/lib/event_bus/event_source.ex b/lib/event_bus/event_source.ex
@@ -1,6 +1,6 @@
 defmodule EventBus.EventSource do
   @moduledoc """
-  Event builder and notifier blocks/yields for EventBus
+  Event builder and notifier blocks/yields for EventBus.
   """
 
   alias EventBus.Model.Event
@@ -23,10 +23,10 @@ defmodule EventBus.EventSource do
   end
 
   @doc """
-  Dynamic event builder block with auto setters
+  Dynamic event builder block with auto setters.
 
-  It auto sets id, transaction_id, source, ttl, initialized_at and occurred_at
-  fields when they are not provided in the params
+  It auto sets `:id`, `:transaction_id`, `:source`, `:ttl`, `:initialized_at`,
+  and `:occurred_at` fields when they are not provided in the params.
   """
   defmacro build(params, do: yield) do
     quote do
@@ -58,10 +58,10 @@ defmodule EventBus.EventSource do
   end
 
   @doc """
-  Dynamic event emitter block with auto setters
+  Dynamic event emitter block with auto setters.
 
-  It auto sets id, transaction_id, source, ttl, initialized_at and occurred_at
-  fields when they are not provided in the params
+  It auto sets `:id`, `:transaction_id`, `:source`, `:ttl`, `:initialized_at`,
+  and `:occurred_at` fields when they are not provided in the params.
   """
   defmacro notify(params, do: yield) do
     quote do

diff --git a/lib/event_bus/models/event.ex b/lib/event_bus/models/event.ex
@@ -1,6 +1,6 @@
 defmodule EventBus.Model.Event do
   @moduledoc """
-  Structure and type for Event model
+  Structure and type for Event model.
   """
 
   @enforce_keys [:id, :topic, :data]
@@ -17,7 +17,7 @@ defmodule EventBus.Model.Event do
   ]
 
   @typedoc """
-  Definition of the Event struct
+  Definition of the Event struct.
 
   * :id - Identifier
   * :transaction_id - Transaction identifier, if event belongs to a transaction
@@ -40,8 +40,8 @@ defmodule EventBus.Model.Event do
         }
 
   @doc """
-  Calculate the duration of the event, and simple answer of how long does it
-  take to generate this event
+  Calculates the duration of the event, and simple answer of how long does it
+  take to generate this event.
   """
   @spec duration(__MODULE__.t()) :: integer()
   def duration(%__MODULE__{

diff --git a/lib/event_bus/utils/base62.ex b/lib/event_bus/utils/base62.ex
@@ -4,15 +4,15 @@ defmodule EventBus.Util.Base62 do
   @mapping '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz'
 
   @doc """
-  Generates partially sequential, base62 unique identifier
+  Generates partially sequential, base62 unique identifier.
   """
   @spec unique_id() :: String.t()
   def unique_id do
     now() <> node_id() <> random(4, 14_776_336)
   end
 
   @doc """
-  Converts given integer to base62
+  Converts given integer to base62.
   """
   @spec encode(integer()) :: String.t()
   def encode(num) when num < 62 do

diff --git a/lib/event_bus/utils/monotonic_time.ex b/lib/event_bus/utils/monotonic_time.ex
@@ -5,7 +5,7 @@ defmodule EventBus.Util.MonotonicTime do
   @eb_time_unit Application.get_env(@eb_app, :time_unit, :microsecond)
 
   @doc """
-  Calculates monotonically increasing current time
+  Calculates monotonically increasing current time.
   """
   @spec now() :: integer()
   def now do

diff --git a/lib/event_bus/utils/regex.ex b/lib/event_bus/utils/regex.ex
@@ -3,7 +3,7 @@ defmodule EventBus.Util.Regex do
   # Regex util for event bus
 
   @doc """
-  It checks if the given list of keys includes the key
+  It checks if the given list of keys includes the key.
   """
   @spec superset?(list(String.t() | atom()), String.t() | atom()) :: boolean()
   def superset?(keys, key) do