Update docs

.github/workflows/ci.yml

@@ -33,7 +33,6 @@ jobs:
         - otp_version: 21
           send_coverage: true
           run_dialyzer: true
-          build_docs: true
 
         - otp_version: 20
 
@@ -72,9 +71,6 @@ jobs:
       run: make dialyzer
       timeout-minutes: 8
 
-    - if: matrix.build_docs
-      run: make doc
-
     - if: matrix.send_coverage && success()
       run: ./rebar3 as test coveralls send
       env:
@@ -124,6 +120,46 @@ jobs:
     - if: ${{ !matrix.skip }}
       run: make test_${{ matrix.json_lib }}
 
+  test_docs:
+    name: Test generating documentation
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        include:
+          - elixir: 1.15.x
+            otp_version: 26
+            rebar3: '3.22.1'
+            # hdr_histogram NIF requires the below PR to be merged to build on OTP 26
+            # https://github.com/HdrHistogram/hdr_histogram_erl/pull/44
+            erl_hist: true
+            os: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+    - uses: erlef/setup-beam@v1
+      with:
+        otp-version: ${{matrix.otp_version}}
+        elixir-version: ${{matrix.elixir}}
+        rebar3-version: ${{matrix.rebar3}}
+
+    - if: matrix.old_rebar
+      run: echo "REBAR3=./rebar3" >> $GITHUB_ENV
+
+    - if: matrix.erl_hist
+      run: echo "XPROF_ERL_HIST=true" >> $GITHUB_ENV
+
+    - if: matrix.old_cowboy
+      run: echo "COWBOY_VERSION=1.1.2" >> $GITHUB_ENV
+
+    - name: Cache hex packages
+      uses: actions/cache@v3
+      with:
+        path: $HOME/.cache/rebar3
+        key: ${{ matrix.otp_version }}-rebar3-cache
+
+    - run: make gen_ex_doc
+
   test_elixir:
     name: Test with Elixir (Elixir ${{matrix.elixir}} | OTP ${{matrix.otp_version}})
     runs-on: ${{matrix.os}}

Makefile

@@ -1,6 +1,5 @@
 JS_PRIV=apps/xprof_gui/priv
 BIN_DIR:=node_modules/.bin
-VERSION:=$(shell grep vsn apps/xprof/src/xprof.app.src | cut -d '"' -f 2)
 REBAR3?=$(shell which rebar3 || echo ./rebar3)
 
 # this will update cowboy version based on rebar.config overwriting the lock file
@@ -63,16 +62,19 @@ test_thoas:
 doc:
 	$(REBAR3) edoc
 
-~/.mix/escripts/ex_doc:
-	mix escript.install hex ex_doc --force
-
 ./doc/src/readme.md: README.md
 	sed -e 's|(doc/src/querysyntax.md)|(querysyntax.html)|' \
 	    -e 's|doc/assets/|assets/|' \
 	    -e '1 s|\[!\[.*||' README.md > ./doc/src/readme.md
 
-gen_ex_doc: ~/.mix/escripts/ex_doc ./doc/docs.exs ./doc/src/readme.md ./doc/src/querysyntax.md
-	~/.mix/escripts/ex_doc XProf $(VERSION) "doc/ebin" -c ./doc/docs.exs
+gen_ex_doc: ./doc/src/readme.md
+	$(MAYBE_UPDATE_COWBOY)
+	$(MAYBE_UNLOCK_HIST)
+	$(REBAR3) ex_doc --app xprof_core
+	$(REBAR3) ex_doc --app xprof_gui
+	cp _build/docs/lib/xprof_core/ebin/xprof_core.beam _build/docs/lib/xprof/ebin
+	cp _build/docs/lib/xprof_gui/ebin/xprof_gui_rest.beam _build/docs/lib/xprof/ebin
+	$(REBAR3) ex_doc --app xprof
 
 dialyzer:
 	$(MAYBE_UPDATE_COWBOY)
@@ -82,4 +84,7 @@ dialyzer:
 publish:
 	$(REBAR3) as publish hex publish --deps_from_config
 
-.PHONY: compile dev dev_back_end dev_front_end npm bootstrap_front_end test_front_end build_prod_front_end test doc gen_ex_doc dialyzer publish
+publish_docs: gen_ex_doc
+	./rebar3 as publish hex docs
+
+.PHONY: compile dev dev_back_end dev_front_end npm bootstrap_front_end test_front_end build_prod_front_end test doc gen_ex_doc dialyzer publish publish_docs

apps/xprof/src/xprof.app.src

@@ -11,6 +11,7 @@
  ,{env,[]}
  ,{modules, []}
  ,{files, ["rebar.config", "src/"]}
+ ,{doc, "doc"}
  ,{licenses, ["BSD-3-Clause"]}
  ,{maintainers, ["Marcin Kasprowicz", "Marcin Kolodziej",
                  "Michal Niec", "Pawel Pikula",

apps/xprof_core/src/test_module.erl

@@ -1,6 +1,7 @@
 %%% @doc Module to generate sample data
 %%% start tracing on `test_module:expensive_fun/1'
 %%% @end
+%%% @private
 -module(test_module).
 -export([start/0]).
 

apps/xprof_core/src/xprof_core.erl

@@ -1,3 +1,6 @@
+%%%
+%%% @doc Erlang API to core XProf functionality
+%%%
 -module(xprof_core).
 
 -export([%% Autocomplete
@@ -101,6 +104,7 @@ expand_query(Query) ->
     end.
 
 %% @doc Get loaded modules and functions (MFAs) that match the query string.
+%%
 %% Used for autocomplete suggestions on the GUI.
 -spec get_matching_mfas_pp(binary()) -> [MFA :: binary()].
 get_matching_mfas_pp(Query) ->
@@ -116,7 +120,9 @@ monitor_pp(Query) ->
     monitor_pp(Query, []).
 
 %% @doc Start monitoring based on the specified query string with additional
-%% parameters. Additional parameters have precedence overthe same keys in the
+%% parameters.
+%%
+%% Additional parameters have precedence overthe same keys in the
 %% query.
 -spec monitor_pp(binary(), [{binary(), binary()}])
                 -> ok | {error, Reason :: already_traced | string()}.
@@ -145,7 +151,9 @@ get_all_monitored() ->
     xprof_core_tracer:all_monitored().
 
 %% @doc Return metrics gathered for the given function since the given
-%% timestamp. Each item contains a timestamp and the corresponding histogram
+%% timestamp.
+%%
+%% Each item contains a timestamp and the corresponding histogram
 %% metrics values.
 -spec get_data(xprof_core:mfa_id(), timestamp()) -> [Item] | {error, not_found}
   when Item :: [{time, timestamp()} | {HistKey, number()}],
@@ -155,6 +163,8 @@ get_all_monitored() ->
 get_data(MFA, TimeStamp) ->
     xprof_core_trace_handler:data(MFA, TimeStamp).
 
+%% @doc Return metrics gathered for the given function formatted
+%% according to the active syntax mode.
 get_data_pp(MFA, TimeStamp) ->
     case xprof_core_trace_handler:data(MFA, TimeStamp) of
         {error, _} = Error ->
@@ -177,7 +187,7 @@ get_called_funs(MFA) ->
     xprof_core_vm_info:get_called_funs(MFA).
 
 %% @doc Return list of called functions formatted according to the
-%% active syntax mode
+%% active syntax mode.
 -spec get_called_funs_pp(xprof_core:mfa_id()) -> [MFA :: binary()].
 get_called_funs_pp(MFA) ->
     ModeCb = xprof_core_lib:get_mode_cb(),
@@ -188,14 +198,16 @@ get_called_funs_pp(MFA) ->
 %% Global trace status
 %%
 
-%% @doc Turn on tracing for one or all processes. Additionally tracing can be
-%% paused and resumed for the same process specification (one or all) that was
-%% given earlier.
+%% @doc Turn on tracing for one or all processes.
+%%
+%% Additionally tracing can be paused and resumed for the same process
+%% specification (one or all) that was given earlier.
 -spec trace(pid() | all | pause | resume) -> ok.
 trace(PidOrSpec) ->
     xprof_core_tracer:trace(PidOrSpec).
 
 %% @doc Return current tracing state.
+%%
 %% (The `initialized' status is basically the same as `paused', additionally
 %%  meaning that no tracing was started yet since xprof was started)
 -spec get_trace_status() -> {pid() | all, Status :: initialized | running | paused | overflow}.
@@ -239,13 +251,15 @@ get_captured_data_pp(MFA, Offset) ->
             Error
     end.
 
+%% @private
 args_res2proplist({Index, Pid, CallTime, Args, Res}, ModeCb) ->
     [{id, Index},
      {pid, ModeCb:fmt_term(Pid)},
      {call_time, CallTime},
      {args, ModeCb:fmt_term(Args)},
      {res, format_result(Res, ModeCb)}].
 
+%% @private
 format_result({return_from, Term}, ModeCb) ->
     ModeCb:fmt_term(Term);
 format_result({exception_from, {Class, Reason}}, ModeCb) ->
@@ -284,20 +298,22 @@ rr(Mod) ->
     xprof_core_records:load_records(Mod).
 
 %% @doc Remove all record definitions.
-%% (similar to shell command ```rf('_')''')
+%% (similar to shell command `` rf('_') '')
 -spec rf() -> ok.
 rf() ->
     xprof_core_records:forget_records().
 
-%% @doc Remove selected record definitions. RecNames is a record name or a
-%% list of record names. To remove all record definitions, use '_'.
+%% @doc Remove selected record definitions.
+%%
+%% The argument can be a record name or a list of record names. To
+%% remove all record definitions, use `` '_' ''.
 %% (similar to shell command `rf/1')
 -spec rf(atom() | [atom()]) -> ok.
 rf(RecNameOrNames) ->
     xprof_core_records:forget_records(RecNameOrNames).
 
 %% @doc Return all stored record definitions.
-%% (Similar to shell command `rl()')
+%% (Similar to shell command `rl/0')
 -spec rl() -> [tuple()].
 rl() ->
     xprof_core_records:get_record_defs().
@@ -311,7 +327,9 @@ rl() ->
 set_mode(Mode) ->
     xprof_core_lib:set_mode(Mode).
 
-%% @doc Get syntax mode, if not set explicitly it will be autodetected.
+%% @doc Get syntax mode.
+%%
+%% If not set explicitly it will be autodetected.
 -spec get_mode() -> xprof_core:mode().
 get_mode() ->
     xprof_core_lib:get_mode().

apps/xprof_core/src/xprof_core_app.erl

@@ -1,5 +1,6 @@
 %% @doc XProf Core application callback
 %% @end
+%% @private
 -module(xprof_core_app).
 
 -behaviour(application).

apps/xprof_core/src/xprof_core_cmd.erl

@@ -8,6 +8,7 @@
 %%% - other -> no trace_pattern -> xprof_core_tracer should find out where to send trace based on trace tag (maybe)
 %%%   -> can only be turned off by trace/3
 %%%   - cmd id = ??? (single tracer per cmd-name or trace tag)
+%%% @private
 -module(xprof_core_cmd).
 
 -export([expand_query/1,
@@ -28,7 +29,7 @@
 
 %% Convert param value from syntax-tree format to Erlang term or expression
 %% (Useful to implement some syntactic sugar/shorthands)
--callback param_from_ast(Key :: atom(), Ast :: erl_parse:syntax_tree()) ->
+-callback param_from_ast(Key :: atom(), Ast :: erl_parse:abstract_expr()) ->
     {ok, Value :: term()} | {error, Reason :: term()}.
 
 %% Validate param value and optionally convert to internal format

apps/xprof_core/src/xprof_core_cmd_argdist.erl

@@ -1,3 +1,4 @@
+%% @private
 -module(xprof_core_cmd_argdist).
 
 -behaviour(xprof_core_cmd).

apps/xprof_core/src/xprof_core_cmd_funlatency.erl

@@ -1,3 +1,4 @@
+%% @private
 -module(xprof_core_cmd_funlatency).
 
 -export([mandatory_params/0,

apps/xprof_core/src/xprof_core_elixir_syntax.erl

@@ -1,6 +1,7 @@
 %%%
 %%% @doc Module to parse and format expressions in Elixir syntax
 %%%
+%%% @private
 -module(xprof_core_elixir_syntax).
 
 -behaviour(xprof_core_language).
@@ -25,7 +26,7 @@
 
 %% Elixir quoted expressions
 -type ex_quoted() :: tuple() | ex_literal().
--type ex_literal() :: atom() | number() | binary() | fun((...) -> any()) | {any(), any()} | [any()].
+-type ex_literal() :: atom() | number() | binary() | fun() | {any(), any()} | list().
 %% Erlang abstract syntax tree
 -type erl_ast() :: tuple().
 

apps/xprof_core/src/xprof_core_erlang_syntax.erl

@@ -1,6 +1,7 @@
 %%%
 %%% @doc Module to parse and format expressions in Erlang syntax
 %%%
+%%% @private
 -module(xprof_core_erlang_syntax).
 
 -behaviour(xprof_core_language).

apps/xprof_core/src/xprof_core_hist.erl

@@ -29,6 +29,7 @@
 %%% OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 %%% SOFTWARE.
 
+%%% @private
 -module(xprof_core_hist).
 
 -export([new/2,

apps/xprof_core/src/xprof_core_language.erl

@@ -2,6 +2,7 @@
 %%% @doc Callback functions that need to be implemented
 %%% for a language-specific behaviour
 %%%
+%%% @private
 -module(xprof_core_language).
 
 %% Function for start monitoring
@@ -47,7 +48,7 @@
 -callback fmt_param(xprof_core:param_name()) ->
     Formatted :: binary().
 
--callback fmt_param_and_delim(xprof_core:param()) ->
+-callback fmt_param_and_delim(xprof_core:param_name()) ->
     Formatted :: binary().
 
 -callback fmt_exception(Class :: throw | error | exit, Reason :: term()) ->

apps/xprof_core/src/xprof_core_lib.erl

@@ -1,3 +1,4 @@
+%% @private
 -module(xprof_core_lib).
 
 -export([mfaspec2atom/1,

apps/xprof_core/src/xprof_core_ms.erl

@@ -1,3 +1,4 @@
+%% @private
 -module(xprof_core_ms).
 
 -export([fun2ms/1,

apps/xprof_core/src/xprof_core_query.erl

@@ -1,3 +1,4 @@
+%% @private
 -module(xprof_core_query).
 
 -export([param_to_term/1,

apps/xprof_core/src/xprof_core_records.erl

@@ -1,4 +1,5 @@
 %%% @doc Server to store loaded record definitions.
+%%% @private
 -module(xprof_core_records).
 
 -export([start_link/0,

apps/xprof_core/src/xprof_core_sup.erl

@@ -1,4 +1,5 @@
 %% @doc xprof top level supervisor.
+%% @private
 -module(xprof_core_sup).
 
 -behaviour(supervisor).

apps/xprof_core/src/xprof_core_trace_handler.erl

@@ -5,6 +5,7 @@
 %% registers itself localy under a atom that consists of MFA and xprof_
 %% prefix. The same name is used to create public ETS table that holds entries
 %% with call time stats for every second.
+%% @private
 -module(xprof_core_trace_handler).
 
 -behaviour(gen_server).

apps/xprof_core/src/xprof_core_trace_handler_sup.erl

@@ -1,4 +1,5 @@
 %%% @doc Supervisor
+%%% @private
 -module(xprof_core_trace_handler_sup).
 
 -behaviour(supervisor).

apps/xprof_core/src/xprof_core_tracer.erl

@@ -1,5 +1,6 @@
 %% -*- erlang-indent-level: 4;indent-tabs-mode: nil -*-
 %% ex: ts=4 sw=4 et
+%% @private
 
 -module(xprof_core_tracer).
 

apps/xprof_core/src/xprof_core_vm_info.erl

@@ -1,3 +1,4 @@
+%% @private
 -module(xprof_core_vm_info).
 
 -include_lib("compiler/src/beam_disasm.hrl").