diff options
author | Hans Bolinder <hasse@erlang.org> | 2011-05-06 16:01:56 +0200 |
---|---|---|
committer | Hans Bolinder <hasse@erlang.org> | 2011-05-11 14:20:58 +0200 |
commit | 5a485461a1157fef1bb3ce8426bfd1ad57b5ca52 (patch) | |
tree | d77f79b9a1b98e7bf2bf3886ebec61d504317fc4 /lib/kernel/doc/src/seq_trace.xml | |
parent | 68fe6a14539b82250373ef114d6576e74e1b8f2e (diff) | |
download | otp-5a485461a1157fef1bb3ce8426bfd1ad57b5ca52.tar.gz otp-5a485461a1157fef1bb3ce8426bfd1ad57b5ca52.tar.bz2 otp-5a485461a1157fef1bb3ce8426bfd1ad57b5ca52.zip |
Use Erlang specs and types for documentation
Diffstat (limited to 'lib/kernel/doc/src/seq_trace.xml')
-rw-r--r-- | lib/kernel/doc/src/seq_trace.xml | 95 |
1 files changed, 41 insertions, 54 deletions
diff --git a/lib/kernel/doc/src/seq_trace.xml b/lib/kernel/doc/src/seq_trace.xml index 6c043dd767..1ab955bd8a 100644 --- a/lib/kernel/doc/src/seq_trace.xml +++ b/lib/kernel/doc/src/seq_trace.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1998</year><year>2009</year> + <year>1998</year><year>2011</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -47,17 +47,22 @@ from users.</p> </note> </description> + <datatypes> + <datatype> + <name name="token"/> + <desc> + <p>An opaque term (a tuple) representing a trace token.</p> + </desc> + </datatype> + </datatypes> <funcs> <func> - <name>set_token(Token) -> PreviousToken</name> + <name name="set_token" arity="1"/> <fsummary>Set the trace token</fsummary> - <type> - <v>Token = PreviousToken = term() | []</v> - </type> <desc> - <p>Sets the trace token for the calling process to <c>Token</c>. - If <c>Token == []</c> then tracing is disabled, otherwise - <c>Token</c> should be an Erlang term returned from + <p>Sets the trace token for the calling process to <c><anno>Token</anno></c>. + If <c><anno>Token</anno> == []</c> then tracing is disabled, otherwise + <c><anno>Token</anno></c> should be an Erlang term returned from <c>get_token/0</c> or <c>set_token/1</c>. <c>set_token/1</c> can be used to temporarily exclude message passing from the trace by setting the trace token to empty like this:</p> @@ -72,18 +77,16 @@ seq_trace:set_token(OldToken), % activate the trace token again </desc> </func> <func> - <name>set_token(Component, Val) -> {Component, OldVal}</name> + <name name="set_token" arity="2"/> <fsummary>Set a component of the trace token</fsummary> - <type> - <v>Component = label | serial | Flag</v> - <v> Flag = send | 'receive' | print | timestamp </v> - <v>Val = OldVal -- see below</v> - </type> + <type name="component"/> + <type name="flag"/> + <type name="value"/> <desc> - <p>Sets the individual <c>Component</c> of the trace token to - <c>Val</c>. Returns the previous value of the component.</p> + <p>Sets the individual <c><anno>Component</anno></c> of the trace token to + <c><anno>Val</anno></c>. Returns the previous value of the component.</p> <taglist> - <tag><c>set_token(label, Int)</c></tag> + <tag><c>set_token(label, <anno>Integer</anno>)</c></tag> <item> <p>The <c>label</c> component is an integer which identifies all events belonging to the same sequential @@ -93,31 +96,31 @@ seq_trace:set_token(OldToken), % activate the trace token again </item> <tag><c>set_token(serial, SerialValue)</c></tag> <item> - <p><c>SerialValue = {Previous, Current}</c>. + <p><c>SerialValue = {<anno>Previous</anno>, <anno>Current</anno>}</c>. The <c>serial</c> component contains counters which enables the traced messages to be sorted, should never be set explicitly by the user as these counters are updated automatically. Default is <c>{0, 0}</c>.</p> </item> - <tag><c>set_token(send, Bool)</c></tag> + <tag><c>set_token(send, <anno>Bool</anno>)</c></tag> <item> <p>A trace token flag (<c>true | false</c>) which enables/disables tracing on message sending. Default is <c>false</c>.</p> </item> - <tag><c>set_token('receive', Bool)</c></tag> + <tag><c>set_token('receive', <anno>Bool</anno>)</c></tag> <item> <p>A trace token flag (<c>true | false</c>) which enables/disables tracing on message reception. Default is <c>false</c>.</p> </item> - <tag><c>set_token(print, Bool)</c></tag> + <tag><c>set_token(print, <anno>Bool</anno>)</c></tag> <item> <p>A trace token flag (<c>true | false</c>) which enables/disables tracing on explicit calls to <c>seq_trace:print/1</c>. Default is <c>false</c>.</p> </item> - <tag><c>set_token(timestamp, Bool)</c></tag> + <tag><c>set_token(timestamp, <anno>Bool</anno>)</c></tag> <item> <p>A trace token flag (<c>true | false</c>) which enables/disables a timestamp to be generated for each @@ -127,11 +130,8 @@ seq_trace:set_token(OldToken), % activate the trace token again </desc> </func> <func> - <name>get_token() -> TraceToken</name> + <name name="get_token" arity="0"/> <fsummary>Return the value of the trace token</fsummary> - <type> - <v>TraceToken = term() | []</v> - </type> <desc> <p>Returns the value of the trace token for the calling process. If <c>[]</c> is returned, it means that tracing is not active. @@ -141,13 +141,11 @@ seq_trace:set_token(OldToken), % activate the trace token again </desc> </func> <func> - <name>get_token(Component) -> {Component, Val}</name> + <name name="get_token" arity="1"/> <fsummary>Return the value of a trace token component</fsummary> - <type> - <v>Component = label | serial | Flag</v> - <v> Flag = send | 'receive' | print | timestamp </v> - <v>Val -- see set_token/2</v> - </type> + <type name="component"/> + <type name="flag"/> + <type name="value"/> <desc> <p>Returns the value of the trace token component <c>Component</c>. See @@ -156,33 +154,26 @@ seq_trace:set_token(OldToken), % activate the trace token again </desc> </func> <func> - <name>print(TraceInfo) -> void()</name> + <name name="print" arity="1"/> <fsummary>Put the Erlang term <c>TraceInfo</c>into the sequential trace output</fsummary> - <type> - <v>TraceInfo = term()</v> - </type> <desc> - <p>Puts the Erlang term <c>TraceInfo</c> into the sequential + <p>Puts the Erlang term <c><anno>TraceInfo</anno></c> into the sequential trace output if the calling process currently is executing within a sequential trace and the <c>print</c> flag of the trace token is set.</p> </desc> </func> <func> - <name>print(Label, TraceInfo) -> void()</name> + <name name="print" arity="2"/> <fsummary>Put the Erlang term <c>TraceInfo</c>into the sequential trace output</fsummary> - <type> - <v>Label = int()</v> - <v>TraceInfo = term()</v> - </type> <desc> <p>Same as <c>print/1</c> with the additional condition that - <c>TraceInfo</c> is output only if <c>Label</c> is equal to + <c><anno>TraceInfo</anno></c> is output only if <c>Label</c> is equal to the label component of the trace token.</p> </desc> </func> <func> - <name>reset_trace() -> void()</name> + <name name="reset_trace" arity="0"/> <fsummary>Stop all sequential tracing on the local node</fsummary> <desc> <p>Sets the trace token to empty for all processes on the @@ -194,26 +185,22 @@ seq_trace:set_token(OldToken), % activate the trace token again </desc> </func> <func> - <name>set_system_tracer(Tracer) -> OldTracer</name> + <name name="set_system_tracer" arity="1"/> <fsummary>Set the system tracer</fsummary> - <type> - <v>Tracer = OldTracer = pid() | port() | false</v> - </type> + <type name="tracer"/> <desc> <p>Sets the system tracer. The system tracer can be either a - process or port denoted by <c>Tracer</c>. Returns the previous + process or port denoted by <c><anno>Tracer</anno></c>. Returns the previous value (which can be <c>false</c> if no system tracer is active).</p> - <p>Failure: <c>{badarg, Info}}</c> if <c>Pid</c> is not an + <p>Failure: <c>{badarg, Info}}</c> if <c><anno>Pid</anno></c> is not an existing local pid.</p> </desc> </func> <func> - <name>get_system_tracer() -> Tracer</name> + <name name="get_system_tracer" arity="0"/> <fsummary>Return the pid() or port() of the current system tracer.</fsummary> - <type> - <v>Tracer = pid() | port() | false</v> - </type> + <type name="tracer"/> <desc> <p>Returns the pid or port identifier of the current system tracer or <c>false</c> if no system tracer is activated.</p> |