Generating docs with ExDoc instead of EDoc (#308)

* Remove code for OTP < 21 * Add format check to CI * Generating docs with ExDoc instead of EDoc Uses the rebar3 plugin `rebar3_ex_doc`. Can be used by `rebar3 ex_doc`.
gen-smtp · Feb 14, 2022 · c6f25a7 · c6f25a7
1 parent 197e7ea
commit c6f25a7
Show file tree

Hide file tree

Showing 8 changed files with 31 additions and 24 deletions.
diff --git a/.editorconfig b/.editorconfig
@@ -8,10 +8,10 @@ end_of_line = lf
 insert_final_newline = true
 trim_trailing_whitespace = true
 
-[*.{config,src}]
+[*.{config, src}]
 indent_style = space
 
-[*.{md,markdown}]
+[*.md]
 indent_style = space
 trim_trailing_whitespace = false
 

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -12,7 +12,7 @@ jobs:
       matrix:
         os: [ubuntu-latest]
         otp: ["24", "23", "22"]
-        rebar3: ["3.17.0"]
+        rebar3: ["3.18.0"]
         profile: [test, ranch_v2]
         include:
           - os: ubuntu-latest
@@ -51,6 +51,9 @@ jobs:
       - name: Xref
         run: make xref
 
+      - name: Format
+        run: rebar3 fmt --check
+
       - name: Test
         run: make test REBAR_PROFILE=${{ matrix.profile }}
 

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -1,4 +1,4 @@
-name: Doc
+name: Docs
 
 on:
   push:
@@ -11,14 +11,14 @@ on:
 jobs:
 
   docs:
-    name: Build EDoc on OTP ${{ matrix.otp }}
+    name: Generate docs on OTP ${{ matrix.otp }}
     runs-on: ${{ matrix.os }}
 
     strategy:
       matrix:
         os: [ubuntu-latest]
-        otp: ["24"]
-        rebar3: ["3.17.0"]
+        otp: ["24"] # https://www.erlang.org/downloads
+        rebar3: ["3.18.0"] # https://www.rebar3.org
 
     steps:
       - uses: actions/checkout@v2
@@ -35,5 +35,5 @@ jobs:
           key: ${{ runner.os }}-hex-${{ hashFiles('**/rebar.lock') }}
           restore-keys: ${{ runner.os }}-hex-
 
-      - name: Build EDoc
-        run: make docs
+      - name: Generate docs by ExDoc
+        run: rebar3 ex_doc
diff --git a/Makefile b/Makefile
@@ -8,7 +8,7 @@ clean:
 	@rebar3 clean -a
 
 test:
-	ERL_AFLAGS="-s ssl" 
+	ERL_AFLAGS="-s ssl"
 	rebar3 as $(REBAR_PROFILE) eunit -c
 
 proper:
@@ -23,7 +23,10 @@ dialyze:
 xref:
 	rebar3 as test xref
 
+format:
+	rebar3 fmt
+
 docs:
-	rebar3 edoc
+	rebar3 ex_doc
 
 .PHONY: compile clean test dialyze
diff --git a/README.markdown → README.md b/README.markdown → README.md
@@ -1,8 +1,8 @@
 # gen_smtp
 
 [![Hex pm](http://img.shields.io/hexpm/v/gen_smtp.svg?style=flat)](https://hex.pm/packages/gen_smtp)
-[![CI](https://github.com/gen-smtp/gen_smtp/workflows/CI/badge.svg)](https://github.com/gen-smtp/gen_smtp/actions?query=workflow%3ACI)
-[![Documentation](https://github.com/gen-smtp/gen_smtp/workflows/Documentation/badge.svg)](https://github.com/gen-smtp/gen_smtp/actions?query=workflow%3ADocumentation)
+[![CI](https://github.com/gen-smtp/gen_smtp/actions/workflows/ci.yml/badge.svg)](https://github.com/gen-smtp/gen_smtp/actions/workflows/ci.yml)
+[![Docs](https://github.com/gen-smtp/gen_smtp/actions/workflows/docs.yml/badge.svg)](https://github.com/gen-smtp/gen_smtp/actions/workflows/docs.yml)
 
 The Erlang SMTP client and server library.
 

diff --git a/rebar.config b/rebar.config
@@ -20,8 +20,10 @@
 
 {project_plugins, [
     erlfmt,
+    rebar3_ex_doc,
     rebar3_proper
 ]}.
+
 {erlfmt, [
     write,
     {print_width, 120},
@@ -71,3 +73,12 @@
         ]}
     ]}
 ]}.
+
+{ex_doc, [
+    {source_url, <<"https://github.com/gen-smtp/gen_smtp">>},
+    {extras, [
+        {'README.md', [{title, <<"Overview">>}]},
+        {'LICENSE', [{title, <<"License">>}]}
+    ]},
+    {main, <<"readme">>}
+]}.
diff --git a/src/gen_smtp.app.src b/src/gen_smtp.app.src
@@ -1,6 +1,6 @@
 {application, gen_smtp, [
     {description, "The extensible Erlang SMTP client and server library."},
-    {vsn, "1.1.1"},
+    {vsn, "1.2.0-dev"},
     {applications, [kernel, stdlib, crypto, asn1, public_key, ssl, ranch]},
     {registered, []},
     {licenses, ["BSD-2-Clause"]},

diff --git a/src/gen_smtp_server_session.erl b/src/gen_smtp_server_session.erl
@@ -90,16 +90,7 @@
     options = [] :: [tuple()]
 }).
 
-%% OTP-19: ssl:ssl_option()
-%% OTP-20: ssl:ssl_option()
-%% OTP-21: ssl:tls_server_option()
-%% OTP-22: ssl:tls_server_option()
-%% OTP-23: ssl:tls_server_option()
--ifdef(OTP_RELEASE).
 -type tls_opt() :: ssl:tls_server_option().
--else.
--type tls_opt() :: ssl:ssl_option().
--endif.
 
 -type options() :: [
     {callbackoptions, any()}
@@ -180,7 +171,6 @@
 -optional_callbacks([handle_info/2, handle_AUTH/4, handle_error/3]).
 
 %% @doc Start a SMTP session linked to the calling process.
-%% @see start/3
 -spec start_link(
     Ref :: ranch:ref(),
     Transport :: module(),