Add edoc generation to CI so that it fails if doc have syntax errors

.circleci/config.yml

@@ -93,7 +93,7 @@ orbs:
               paths: ./
 
 
-      dialyzer:
+      dialyzer_and_edoc:
         parallelism: 1
         machine:
           image: ubuntu-1604:201903-01
@@ -110,7 +110,7 @@ orbs:
           - run:
               name: Run Dialyzer
               command: |
-                SKIP_AUTO_COMPILE=true KEEP_COVER_RUNNING=1 ./tools/travis-test.sh -p dialyzer_only -s false
+                SKIP_AUTO_COMPILE=true KEEP_COVER_RUNNING=1 ./tools/travis-test.sh -p dialyzer_and_edoc -s false
 
       small_tests:
         parallelism: 1
@@ -338,8 +338,8 @@ workflows:
             - otp_22
           filters: *all_tags
       # ============= DIALYZER =============
-      - mim/dialyzer:
-          name: dialyzer
+      - mim/dialyzer_and_edoc:
+          name: dialyzer_and_edoc
           otp_package: 22.1.8-1
           context: mongooseim-org
           filters: *all_tags
@@ -422,7 +422,7 @@ workflows:
             - internal_mnesia
             - mysql_redis
             - mssql_mnesia
-            - dialyzer
+            - dialyzer_and_edoc
             - small_tests_22
             - small_tests_21_3
           filters: *all_tags

.travis.yml

@@ -95,7 +95,7 @@ env:
     - PRESET=elasticsearch_and_cassandra_mnesia DB="elasticsearch cassandra"
       REL_CONFIG="with-elasticsearch with-cassandra" TESTSPEC=mam.spec
       ELASTICSEARCH_VERSION=5.6.9 CASSANDRA_VERSION=3.9
-    - PRESET=dialyzer_only SKIP_RELEASE=1 SKIP_BUILD_TESTS=1 SKIP_COV=1 SKIP_REPORT_UPLOAD=1
+    - PRESET=dialyzer_and_edoc SKIP_RELEASE=1 SKIP_BUILD_TESTS=1 SKIP_COV=1 SKIP_REPORT_UPLOAD=1
       # In case you want to test with another ODBC driver, uncomment this
       # - PRESET=odbc_pgsql_mnesia DB=pgsql REL_CONFIG=with-odbc
 

rebar.config

@@ -191,4 +191,5 @@
   {path, ["/tmp", "_build/test/cover"]}
  ]}.
 
-{edoc_opts, [{preprocess, true}]}.
+{edoc_opts, [{dir, "edoc"}, %% there is already doc direcotry with documentation in markdown
+             {preprocess, true}]}.

src/ejabberd_cowboy.erl

@@ -2,17 +2,19 @@
 %%% @doc Common listener/router for modules that use Cowboy.
 %%%
 %%% The 'modules' configuration option should be a list of
-%%% {Host, BasePath, Module} or {Host, BasePath, Module, Opts} tuples,
+%%% `{Host, BasePath, Module}' or `{Host, BasePath, Module, Opts}' tuples,
 %%% where a Host of "_" will match any host.
 %%%
 %%% A 'middlewares' configuration option may be specified to configure
 %%% Cowboy middlewares.
 %%%
 %%% Modules may export the following function to configure Cowboy
 %%% routing for sub-paths:
+%%% ```
 %%% cowboy_router_paths(BasePath, Opts) ->
 %%%   [{PathMatch, Handler, NewOpts}]
-%%% If not implemented, [{BasePath, Module, []|Opts}] is assumed.
+%%% '''
+%%% If not implemented, `[{BasePath, Module, [] | Opts}]' is assumed.
 %%% @end
 %%%===================================================================
 -module(ejabberd_cowboy).
@@ -289,7 +291,7 @@ maybe_insert_max_connections(TransportOpts, Opts) ->
 %% @doc
 %% Store trails, this need for generate swagger documentation
 %% Add to Trails each of modules where used trails behaviour
-%% The modules must be added into `mongooseim.cfg`in `swagger` section
+%% The modules must be added into `mongooseim.cfg' in `swagger' section
 %% @end
 %% -------------------------------------------------------------------
 trails_store(Modules) ->

src/event_pusher/mod_event_pusher_push_plugin.erl

@@ -25,20 +25,20 @@
          publish_notification/5]).
 
 
-%% @doc used for filtering push notifications. A push notification is triggered for a given
+%% used for filtering push notifications. A push notification is triggered for a given
 %% message only if this callback returns `true`.
 -callback should_publish(Acc :: mongooseim_acc:t(),
                          Event :: mod_event_pusher:event(),
                          Services :: [mod_event_pusher_push:publish_service()]) ->
     [mod_event_pusher_push:publish_service()].
 
-%% @doc a separate interface for rejecting the event publishing (e.g. when
+%% a separate interface for rejecting the event publishing (e.g. when
 %% message doesn't have a body) or creating push notification payload.
 -callback prepare_notification(Acc :: mongooseim_acc:t(),
                                Event :: mod_event_pusher:event()) ->
     push_payload() | skip.
 
-%% @doc does the actual push. By default it pushes to the registered pubsub
+%% does the actual push. By default it pushes to the registered pubsub
 %% nodes (or executes the internal hook in case of a publish to a virtual domain).
 -callback publish_notification(Acc :: mongooseim_acc:t(),
                                Event :: mod_event_pusher:event(),

tools/travis-test.sh

@@ -246,10 +246,12 @@ build_pkg () {
   set +e
 }
 
-if [ "$PRESET" == "dialyzer_only" ]; then
+if [ "$PRESET" == "dialyzer_and_edoc" ]; then
   tools/print-dots.sh start
   tools/print-dots.sh monitor $$
+  set -e
   ./rebar3 dialyzer
+  ./rebar3 edoc
   RESULT=$?
   tools/print-dots.sh stop
   exit ${RESULT}