From f1792bbfc5e8d40213cbc29f8faaeefed33a79b9 Mon Sep 17 00:00:00 2001 From: Michal Piotrowski Date: Tue, 31 Mar 2020 19:12:20 +0200 Subject: [PATCH 1/4] Add edoc generation to CI so that it fails if doc have syntax errors --- .circleci/config.yml | 2 +- .travis.yml | 2 +- rebar.config | 3 ++- tools/travis-test.sh | 4 +++- 4 files changed, 7 insertions(+), 4 deletions(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index de8f195e19f..4fea12c83c9 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -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 diff --git a/.travis.yml b/.travis.yml index d5d0379cb02..beb4af08e04 100644 --- a/.travis.yml +++ b/.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 diff --git a/rebar.config b/rebar.config index c5800f8b303..a84e611b9d0 100644 --- a/rebar.config +++ b/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}]}. diff --git a/tools/travis-test.sh b/tools/travis-test.sh index 0d00e7085a2..7e6bd4cf267 100755 --- a/tools/travis-test.sh +++ b/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} From cf872a41fcf2ddcbbcc981f39b52c456dda918ef Mon Sep 17 00:00:00 2001 From: Michal Piotrowski Date: Tue, 31 Mar 2020 19:20:42 +0200 Subject: [PATCH 2/4] Remove @doc before `-callback` definition Currently edoc is not able to generate documentation for callbacks. Instead it thinks this is documentation for the first function in the module defined below the callbacks. --- src/event_pusher/mod_event_pusher_push_plugin.erl | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/event_pusher/mod_event_pusher_push_plugin.erl b/src/event_pusher/mod_event_pusher_push_plugin.erl index f2082384973..017952f32fe 100644 --- a/src/event_pusher/mod_event_pusher_push_plugin.erl +++ b/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(), From c94953a25442252e2483125d7db8cc26e0749fd5 Mon Sep 17 00:00:00 2001 From: Michal Piotrowski Date: Tue, 31 Mar 2020 19:26:56 +0200 Subject: [PATCH 3/4] Use proper edoc syntax for code and snippets highlighting --- src/ejabberd_cowboy.erl | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/src/ejabberd_cowboy.erl b/src/ejabberd_cowboy.erl index 526228963d8..e90e431de8e 100644 --- a/src/ejabberd_cowboy.erl +++ b/src/ejabberd_cowboy.erl @@ -2,7 +2,7 @@ %%% @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 @@ -10,9 +10,11 @@ %%% %%% 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) -> From 667a784b8528bf40081298d6500a13f32c71774b Mon Sep 17 00:00:00 2001 From: Michal Piotrowski Date: Tue, 31 Mar 2020 19:30:23 +0200 Subject: [PATCH 4/4] Change CircleCI's dialyzer job name to dialyzer_and_edoc --- .circleci/config.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index 4fea12c83c9..89e9cefb3f4 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -93,7 +93,7 @@ orbs: paths: ./ - dialyzer: + dialyzer_and_edoc: parallelism: 1 machine: image: ubuntu-1604:201903-01 @@ -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