Skip to content

Commit

Permalink
tools: Add specs and types for documentation
Browse files Browse the repository at this point in the history 
When at it, a few minor issues have been fixed in the docs.
  • Loading branch information
@uabboli
uabboli committed Nov 10, 2020
1 parent d4cb377 commit 5040a7a
Show file tree
Hide file tree
Showing 19 changed files with 2,475 additions and 1,598 deletions.
453 changes: 200 additions & 253 deletions lib/tools/doc/src/cover.xml
View file

Large diffs are not rendered by default.

199 changes: 80 additions & 119 deletions lib/tools/doc/src/cprof.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -60,69 +60,61 @@
of tracing since no trace message has to be generated. Some
measurements indicates performance degradation in the vicinity
of 10 percent.
<marker id="analyse"></marker>
</p>
</p>
</description>
<funcs>
<func>
<name since="">analyse() -> {AllCallCount, ModAnalysisList}</name>
<name since="">analyse(Limit) -> {AllCallCount, ModAnalysisList}</name>
<name since="">analyse(Mod) -> ModAnalysis</name>
<name since="">analyse(Mod, Limit) -> ModAnalysis</name>
<name name="analyse" arity="0" since=""></name>
<name name="analyse" arity="1" clause_i="1" since=""></name>
<name name="analyse" arity="1" clause_i="2" since=""></name>
<name name="analyse" arity="2" since=""></name>
<fsummary>Collect and analyse call counters.</fsummary>
<type>
<v>Limit = integer()</v>
<v>Mod = atom()</v>
<v>AllCallCount = integer()</v>
<v>ModAnalysisList = [ModAnalysis]</v>
<v>ModAnalysis = {Mod, ModCallCount, FuncAnalysisList}</v>
<v>ModCallCount = integer()</v>
<v>FuncAnalysisList = [{{Mod, Func, Arity}, FuncCallCount}]</v>
<v>Func = atom()</v>
<v>Arity = integer()</v>
<v>FuncCallCount = integer()</v>
</type>
<type name="mod_analysis_list"/>
<type name="mod_analysis"/>
<type name="func_analysis_list"/>
<desc>
<p>Collects and analyses the call counters presently in the
node for either module <c>Mod</c>, or for all modules
node for either module <c><anno>Mod</anno></c>, or for all modules
(except <c>cprof</c> itself), and returns: </p>
<taglist>
<tag><c>FuncAnalysisList</c></tag>
<tag><c><anno>FuncAnalysisList</anno></c></tag>
<item>A list of tuples, one for each function in a module, in
decreasing <c>FuncCallCount</c> order.</item>
<tag><c>ModCallCount</c></tag>
<item>The sum of <c>FuncCallCount</c> values for all
functions in module <c>Mod</c>.</item>
<tag><c>AllCallCount</c></tag>
<item>The sum of <c>ModCallCount</c> values for all modules
concerned in <c>ModAnalysisList</c>.</item>
<tag><c>ModAnalysisList</c></tag>
decreasing <c><anno>FuncCallCount</anno></c> order.</item>
<tag><c><anno>ModCallCount</anno></c></tag>
<item>The sum of <c><anno>FuncCallCount</anno></c> values for all
functions in module <c><anno>Mod</anno></c>.</item>
<tag><c><anno>AllCallCount</anno></c></tag>
<item>The sum of <c><anno>ModCallCount</anno></c> values for all modules
concerned in <c><anno>ModAnalysisList</anno></c>.</item>
<tag><c><anno>ModAnalysisList</anno></c></tag>
<item>A list of tuples, one for each module except
<c>cprof</c>, in decreasing <c>ModCallCount</c> order.</item>
<c>cprof</c>, in decreasing <c><anno>ModCallCount</anno></c> order.</item>
</taglist>
<p>If call counters are still running while
<c>analyse/0..2</c> is executing, you might get an
inconsistent result. This happens if the process executing
<c>analyse/0..2</c> gets scheduled out so some other process
can increment the counters that are being analysed, Calling
<c>pause()</c> before analysing takes care of the problem.
<seemfa marker="#pause/0"><c>pause()</c></seemfa>
before analysing takes care of the problem.
</p>
<p>If the <c>Mod</c> argument is given, the result contains a
<c>ModAnalysis</c> tuple for module <c>Mod</c> only,
otherwise the result contains one <c>ModAnalysis</c> tuple
for all modules returned from <c>code:all_loaded()</c>
except <c>cprof</c> itself.
<p>If the <c><anno>Mod</anno></c> argument is given, the
result contains a <c><anno>ModAnalysis</anno></c> tuple for
module <c><anno>Mod</anno></c> only, otherwise the result
contains one <c><anno>ModAnalysis</anno></c> tuple for all
modules returned from <seemfa
marker="kernel:code#all_loaded/0">
<c>code:all_loaded()</c></seemfa> except <c>cprof</c> itself.
</p>
<p>All functions with a <c>FuncCallCount</c> lower than
<c>Limit</c> are excluded from <c>FuncAnalysisList</c>. They
are still included in <c>ModCallCount</c>, though.
The default value for <c>Limit</c> is <c>1</c>.
<marker id="pause_0"></marker>
</p>
<p>All functions with a <c><anno>FuncCallCount</anno></c>
lower than <c><anno>Limit</anno></c> are excluded from
<c><anno>FuncAnalysisList</anno></c>. They are still included
in <c><anno>ModCallCount</anno></c>, though. The default value
for <c><anno>Limit</anno></c> is <c>1</c>.</p>
</desc>
</func>
<func>
<name since="">pause() -> integer()</name>
<name name="pause" arity="0" since=""></name>
<fsummary>Pause running call count trace for all functions.</fsummary>
<desc>
<p>Pause call count tracing for all functions in all modules
Expand All @@ -131,73 +123,57 @@
<c>(pause({'_','_','_'})+stop({on_load}))</c>.
</p>
<p>See also
<seeerl marker="#pause">pause/1..3</seeerl> below.
<marker id="pause"></marker>
</p>
<seemfa marker="#pause/1"><c>pause/1..3</c></seemfa> below.
</p>
</desc>
</func>
<func>
<name since="">pause(FuncSpec) -> integer()</name>
<name since="">pause(Mod, Func) -> integer()</name>
<name since="">pause(Mod, Func, Arity) -> integer()</name>
<name name="pause" arity="1" since=""></name>
<name name="pause" arity="2" since=""></name>
<name name="pause" arity="3" since=""></name>
<fsummary>Pause running call count trace for matching functions.</fsummary>
<type>
<v>FuncSpec = Mod | {Mod,Func,Arity}, {FS}</v>
<v>Mod = atom()</v>
<v>Func = atom()</v>
<v>Arity = integer()</v>
<v>FS = term()</v>
</type>
<desc>
<p>Pause call counters for matching functions in matching
modules. The <c>FS</c> argument can be used to
specify the first argument to
<c>erlang:trace_pattern/3</c>. See erlang(3).

<p>Pause call counters for matching functions in matching
modules. The <c><anno>FS</anno></c> argument can be used to
specify the first argument to <seemfa
marker="erts:erlang#trace_pattern/3"><c>erlang:trace_pattern/3</c></seemfa>.
</p>
<p>The call counters for all matching functions that
has got call count breakpoints are paused at their current
count.
</p>
<p>Return the number of matching functions that can have
call count breakpoints, the same as
<c>start/0..3</c> with the same arguments would have
returned.
<marker id="restart"></marker>
</p>
<seemfa marker="#start/0"><c>start/0..3</c></seemfa>
with the same arguments would have returned.
</p>
</desc>
</func>
<func>
<name since="">restart() -> integer()</name>
<name since="">restart(FuncSpec) -> integer()</name>
<name since="">restart(Mod, Func) -> integer()</name>
<name since="">restart(Mod, Func, Arity) -> integer()</name>
<name name="restart" arity="0" since=""></name>
<name name="restart" arity="1" since=""></name>
<name name="restart" arity="2" since=""></name>
<name name="restart" arity="3" since=""></name>
<fsummary>Restart existing call counters for matching functions.</fsummary>
<type>
<v>FuncSpec = Mod | {Mod,Func,Arity}, {FS}</v>
<v>Mod = atom()</v>
<v>Func = atom()</v>
<v>Arity = integer()</v>
<v>FS = term()</v>
</type>
<desc>
<p>Restart call counters for the matching functions in
matching modules that are call count traced. The <c>FS</c>
argument can be used to specify the first argument to
<c>erlang:trace_pattern/3</c>. See erlang(3).
matching modules that are call count traced. The <c><anno>FS</anno></c>
argument can be used to specify the first argument to <seemfa
marker="erts:erlang#trace_pattern/3"><c>erlang:trace_pattern/3</c></seemfa>.
</p>
<p>The call counters for all matching functions that has got
call count breakpoints are set to zero and running.
</p>
<p>Return the number of matching functions that can have
call count breakpoints, the same as
<c>start/0..3</c> with the same arguments would have
returned.
<marker id="start_0"></marker>
</p>
<seemfa marker="#start/0"><c>start/0..3</c></seemfa>
with the same arguments would have returned.
</p>
</desc>
</func>
<func>
<name since="">start() -> integer()</name>
<name name="start" arity="0" since=""></name>
<fsummary>Start call count tracing for all functions.</fsummary>
<desc>
<p>Start call count tracing for all functions in all modules,
Expand All @@ -206,41 +182,33 @@
<c>(start({'_','_','_'})+start({on_load}))</c>.
</p>
<p>See also
<seeerl marker="#start">start/1..3</seeerl> below.
<marker id="start"></marker>
</p>
<seemfa marker="#start/1"><c>start/1..3</c></seemfa> below.
</p>
</desc>
</func>
<func>
<name since="">start(FuncSpec) -> integer()</name>
<name since="">start(Mod, Func) -> integer()</name>
<name since="">start(Mod, Func, Arity) -> integer()</name>
<name name="start" arity="1" since=""></name>
<name name="start" arity="2" since=""></name>
<name name="start" arity="3" since=""></name>
<fsummary>Start call count tracing for matching functions.</fsummary>
<type>
<v>FuncSpec = Mod | {Mod,Func,Arity}, {FS}</v>
<v>Mod = atom()</v>
<v>Func = atom()</v>
<v>Arity = integer()</v>
<v>FS = term()</v>
</type>
<desc>
<p>Start call count tracing for matching functions in matching
modules. The <c>FS</c> argument can be used to specify the
first argument to <c>erlang:trace_pattern/3</c>, for example
<c>on_load</c>. See erlang(3).
modules. The <c><anno>FS</anno></c> argument can be used to specify the
first argument to <seemfa
marker="erts:erlang#trace_pattern/3"><c>erlang:trace_pattern/3</c></seemfa>,
for example <c>on_load</c>.
</p>
<p>Set call count breakpoints on the matching functions that
has no call count breakpoints. Call counters
are set to zero and running for all matching functions.
</p>
<p>Return the number of matching functions that has got
call count breakpoints.
<marker id="stop_0"></marker>
</p>
</p>
</desc>
</func>
<func>
<name since="">stop() -> integer()</name>
<name name="stop" arity="0" since=""></name>
<fsummary>Stop call count tracing for all functions.</fsummary>
<desc>
<p>Stop call count tracing for all functions in all modules,
Expand All @@ -249,36 +217,29 @@
<c>(stop({'_','_','_'})+stop({on_load}))</c>.
</p>
<p>See also
<seeerl marker="#stop">stop/1..3</seeerl> below.
<marker id="stop"></marker>
</p>
<seemfa marker="#stop/1"><c>stop/1..3</c></seemfa> below.
</p>
</desc>
</func>
<func>
<name since="">stop(FuncSpec) -> integer()</name>
<name since="">stop(Mod, Func) -> integer()</name>
<name since="">stop(Mod, Func, Arity) -> integer()</name>
<name name="stop" arity="1" since=""></name>
<name name="stop" arity="2" since=""></name>
<name name="stop" arity="3" since=""></name>
<fsummary>Stop call count tracing for matching functions.</fsummary>
<type>
<v>FuncSpec = Mod | {Mod,Func,Arity}, {FS}</v>
<v>Mod = atom()</v>
<v>Func = atom()</v>
<v>Arity = integer()</v>
<v>FS = term()</v>
</type>
<desc>
<p>Stop call count tracing for matching functions in matching
modules. The <c>FS</c> argument can be used to specify the
first argument to <c>erlang:trace_pattern/3</c>, for example
<c>on_load</c>. See erlang(3).
modules. The <c><anno>FS</anno></c> argument can be used to specify the
first argument to <seemfa
marker="erts:erlang#trace_pattern/3"><c>erlang:trace_pattern/3</c></seemfa>,
for example <c>on_load</c>.
</p>
<p>Remove call count breakpoints from the matching functions that
has call count breakpoints.
</p>
<p>Return the number of matching functions that can have
call count breakpoints, the same as
<c>start/0..3</c> with the same arguments would have
returned.
<seemfa marker="#start/0"><c>start/0..3</c></seemfa>
with the same arguments would have returned.
</p>
</desc>
</func>
Expand Down
Loading

0 comments on commit 5040a7a

Please sign in to comment.