HCA-Healthcare · DarkMarmot · Oct 13, 2024 · Sep 1, 2024 · Sep 1, 2024 · Sep 1, 2024
diff --git a/README.md b/README.md
@@ -3,11 +3,6 @@
 [![hex.pm downloads](https://img.shields.io/hexpm/dt/elixir_hl7.svg)](https://hex.pm/packages/elixir_hl7)
 [![hex.pm license](https://img.shields.io/hexpm/l/elixir_hl7.svg)](https://hex.pm/packages/elixir_hl7)
 
-Note: We are now building a simpler and more Elixir-friendly API for this library, centered on
-the `HL7` and `HL7.Path` modules. These will hopefully lead to the deprecation of
-`HL7.Query` and much of the related code. These will likely not be removed for some time, and their
-removal will coincide with a major version release. For now, the two systems can exchange data when needed.
-
 An Elixir library for working with HL7 v2.x healthcare data 
 
 Elixir HL7 provides functions to parse, query and modify healthcare data that conforms to the HL7 v2.x standards. 
@@ -23,9 +18,18 @@ You can learn more about HL7 here:
 
 Please [report an issue](https://github.com/HCA-Healthcare/elixir-hl7/issues) if something appears to be handled incorrectly.
 
-## Getting started
+> ### Note {: .warning}
+>
+>
+> We are building a simpler and more Elixir-friendly API for this library, centered on
+> the `HL7` and `HL7.Path` modules. 
+> 
+> The new API will lead to the deprecation of `HL7.Query` and related code. 
+> 
+> These will likely not be removed for some time, and their
+> removal will coincide with a major version release. For now, the two systems can exchange data when needed.
 
-Full documentation can be found at [hex.pm](https://hexdocs.pm/elixir_hl7/readme.html).
+## Getting started
 
 Add this library to your mix.exs file:
 
@@ -35,9 +39,20 @@ defp deps do
 end
 ```
 
-Check out the `HL7.Examples` module for sample data that you can use to explore the API. 
+## Use the Tabs Below to Explore the Library
+
+<!-- tabs-open -->
 
-## Route
+### Examples 
+
+The `HL7.Examples` module contains functions with sample data that you can use in unit tests or to explore the API,
+
+    iex> hl7_text = HL7.Examples.wikipedia_sample_hl7()
+    ...> to_string()
+    ...> Enum.take(30)
+    "ADT" 
+
+### Route
 
 HL7 messages can be minimally validated to gather header (MSH segment) information for quick routing and acknowledgements.
 
@@ -48,7 +63,7 @@ HL7 messages can be minimally validated to gather header (MSH segment) informati
 
 See the `HL7.RawMessage` and `HL7.Header` modules for more information.
 
-## Parse
+### Parse
 
 HL7 messages can be fully parsed into lists of lists and strings to provide a compact representation of the message structure.
 
@@ -83,7 +98,7 @@ It's also possible to modify the data within a segment (but it is much easier to
 
 See the `HL7.Message` and `HL7.Segment` modules for more information.
 
-## Query
+### Query
 
 Advanced manipulation and analysis of HL7 messages can be performed with the `HL7.Query` module. 
 
@@ -161,6 +176,8 @@ The following query extracts each Common Order (ORC) group's OBX segments and ou
 
 
 See the `HL7.Query` module for more information.
+
+
 
 ## Create
 
@@ -169,6 +186,9 @@ HL7 messages can be constructed from scratch with the `HL7.Message` module. Pass
 
 The final raw message can be produced by invoking the `to_string/1` protocol on either the `HL7.Query` or `HL7.Message` structs.
 
+<!-- tabs-close -->
+
+
 ## Files
 
 The `HL7` module contains utility functions to open file streams of HL7 message content with support for MLLP and standard `:line` storage. 

diff --git a/lib/hl7/field_grammar.ex b/lib/hl7/field_grammar.ex
@@ -1,5 +1,8 @@
 defmodule HL7.FieldGrammar do
-  @deprecated "Use HL7.Path.new/1 instead"
+  @moduledoc deprecated: "Use `HL7` instead"
+  @moduledoc "Represents an HL7 path."
+
+  @doc deprecated: "Use `HL7.Path.new/1` instead"
   def to_indices(schema) do
     HL7.Path.new(schema)
   end

diff --git a/lib/hl7/invalid_grammar.ex b/lib/hl7/invalid_grammar.ex
@@ -1,8 +1,7 @@
 defmodule HL7.InvalidGrammar do
-  @moduledoc """
-  Contains information concerning any failed attempt to parse Field or Segment Grammar Notations.
-  """
+  @moduledoc false
 
+  # Contains information concerning any failed attempt to parse Field or Segment Grammar Notations.
   @type invalid_token :: %HL7.InvalidGrammar{
           invalid_token: String.t(),
           schema: String.t(),

diff --git a/lib/hl7/invalid_message.ex b/lib/hl7/invalid_message.ex
@@ -1,6 +1,9 @@
 defmodule HL7.InvalidMessage do
+  @moduledoc deprecated: "Use errors from `HL7` instead"
+
   @moduledoc """
-  Contains information concerning any failed attempt to parse an HL7 message, generally MSH-related.
+  Contains information concerning any failed attempt
+  to parse an HL7 message, generally MSH-related
   """
 
   @type t :: %HL7.InvalidMessage{

diff --git a/lib/hl7/lexers/default.ex b/lib/hl7/lexers/default.ex
@@ -1,4 +1,5 @@
 defmodule HL7.Lexers.Default do
+  @moduledoc false
   @carriage_return 4
   @field 3
   @repetition 2

diff --git a/lib/hl7/lexers/default_with_copy.ex b/lib/hl7/lexers/default_with_copy.ex
@@ -1,4 +1,5 @@
 defmodule HL7.Lexers.DefaultWithCopy do
+  @moduledoc false
   @carriage_return 4
   @field 3
   @repetition 2

diff --git a/lib/hl7/lexers/dynamic.ex b/lib/hl7/lexers/dynamic.ex
@@ -1,4 +1,5 @@
 defmodule HL7.Lexers.Dynamic do
+  @moduledoc false
   @carriage_return 4
   @field 3
   @repetition 2

diff --git a/lib/hl7/lexers/dynamic_with_copy.ex b/lib/hl7/lexers/dynamic_with_copy.ex
@@ -1,4 +1,5 @@
 defmodule HL7.Lexers.DynamicWithCopy do
+  @moduledoc false
   @carriage_return 4
   @field 3
   @repetition 2

diff --git a/lib/hl7/list_parser.ex b/lib/hl7/list_parser.ex
@@ -1,4 +1,5 @@
 defmodule HL7.Parser do
+  @moduledoc false
   @carriage_return 4
   @field 3
   @repetition 2

diff --git a/lib/hl7/message.ex b/lib/hl7/message.ex
@@ -4,14 +4,19 @@ defmodule HL7.Message do
   @moduledoc """
   Creates, parses and modifies HL7 messages with a focus on performance. Contains a list of parsed segments and header metadata.
 
-  Use `Hl7.Message.new/2` to create an `Hl7.Message` struct that contains a fully parsed HL7 message alongside header metadata.
+  Use `HL7.Message.new/2` to create an `t:HL7.Message.t/0` struct that contains a fully parsed HL7 message alongside header metadata.
   The parsed data is represented as minimally as possible as lists of string and lists.
 
+
   The second argument is an options map supporting the following values:
 
   `copy: true` -- Will create binary copies while parsing to avoid keeping references.
+
   `validate_string: true` -- Will generate an `HL7.InvalidMessage` if the source text is not UTF-8 compatible.
   """
+
+  @moduledoc deprecated: "Use `HL7` instead."
+
   alias HL7.Path
 
   @segment_terminator "\r"

diff --git a/lib/hl7/path_parser.ex b/lib/hl7/path_parser.ex
@@ -2,6 +2,8 @@
 # Generated at 2024-04-25 18:02:03Z.
 
 defmodule HL7.PathParser do
+  @moduledoc false
+
   @doc """
   Parses the given `binary` as parse.
 

diff --git a/lib/hl7/query.ex b/lib/hl7/query.ex
@@ -3,6 +3,8 @@ defmodule HL7.Query do
 
   alias HL7.Path
 
+  @moduledoc deprecated: "Use `HL7` instead"
+
   @moduledoc """
   Queries and modifies HL7 messages using Field and Segment Grammar Notations with a pipeline-friendly API and set-based
   operations.

diff --git a/lib/hl7/raw_message.ex b/lib/hl7/raw_message.ex
@@ -4,9 +4,11 @@ defmodule HL7.RawMessage do
   @moduledoc """
   Contains the raw text of an HL7 message alongside parsed header metadata from the MSH segment.
 
-  Use `HL7.Message.raw/1` to generate the `HL7.RawMessage` struct.
+  Use `HL7.Message.raw/1` to generate the `t:HL7.RawMessage.t/0` struct
   """
 
+  @moduledoc deprecated: "Use `HL7.Header` instead"
+
   @type t :: %HL7.RawMessage{
           raw: nil | binary(),
           header: nil | HL7.Header.t()

diff --git a/lib/hl7/segment.ex b/lib/hl7/segment.ex
@@ -5,14 +5,16 @@ defmodule HL7.Segment do
   Filter, parse and modify individual HL7 segments and their fragments.
   """
 
+  @moduledoc deprecated: "Use `HL7` instead"
+
   @type raw_hl7 :: String.t() | HL7.RawMessage.t()
   @type fragment_hl7 :: String.t() | [list() | String.t()]
   @type segment_hl7 :: [fragment_hl7()]
   @type parsed_hl7 :: [segment_hl7()] | HL7.Message.t()
   @type content_hl7 :: raw_hl7() | parsed_hl7()
 
   @doc ~S"""
-  Updates content within a parsed HL7 segment, returning a modified segment whose data has been transformed at the given 
+  Updates content within a parsed HL7 segment, returning a modified segment whose data has been transformed at the given
   indices (starting at 1 as with HL7's convention). The `transform` can be either a `string`, `list` or `fn old_data -> new_data`.
   """
 

diff --git a/lib/hl7/separators.ex b/lib/hl7/separators.ex
@@ -5,6 +5,8 @@ defmodule HL7.Separators do
   Contains HL7 delimiter information (optionally specified by the end system) used to parse or generate HL7 messages.
   """
 
+  @moduledoc deprecated: "Use `HL7` instead"
+
   # default HL7 separators
   # |^~\&#
 

diff --git a/mix.exs b/mix.exs
@@ -11,10 +11,6 @@ defmodule HL7.MixProject do
       elixir: "~> 1.14",
       start_permanent: Mix.env() == :prod,
       deps: deps(),
-      docs: [
-        extras: ["README.md"],
-        main: "readme"
-      ],
       dialyzer: [
         flags: [
           :error_handling,
@@ -29,7 +25,29 @@ defmodule HL7.MixProject do
         "coveralls.post": :test,
         "coveralls.html": :test
       ],
-      aliases: aliases()
+      aliases: aliases(),
+
+      # Docs
+      docs: [
+        api_reference: false,
+        extras: ["README.md"],
+        main: "readme",
+        groups_for_modules: [
+          Deprecated: [
+            HL7.FieldGrammar,
+            HL7.InvalidGrammar,
+            HL7.InvalidMessage,
+            HL7.Message,
+            HL7.Parser,
+            HL7.PathParser,
+            HL7.Query,
+            HL7.RawMessage,
+            HL7.Segment,
+            HL7.Separators
+          ]
+        ],
+        nest_modules_by_prefix: ["HL7"]
+      ]
     ]
   end