Skip to content

Commit d530899

Browse files
thinkversethinkverse
authored
Cleanup reference/zmq documentation
* Fix reference/zmq having returnvalues in wrong order * Add missing parameters sections to reference/zmq * Fix errors being in returnvalues * Fix typo `zmqpoll/poll.xml` * Remove useless noise * Add classname tag for auto linking * Move callback signature to parameters * Remove ZMQContext contructor return value * Fix ZMQContext::getSocket return value * Fix ZMQSocket::recv return value * Fix ZMQSocket::recv errors section Co-authored-by: George Peter Banyard <[email protected]> Closes GH-566.
1 parent c9389e4 commit d530899

File tree

8 files changed

+104
-80
lines changed

8 files changed

+104
-80
lines changed

‎reference/zmq/zmqcontext/construct.xml

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,14 @@
4444
</variablelist>
4545
</para>
4646
</refsect1>
47-
47+
48+
<refsect1 role="errors">
49+
&reftitle.errors;
50+
<para>
51+
Throws <classname>ZMQContextException</classname> if context initialization fails.
52+
</para>
53+
</refsect1>
54+
4855
<refsect1 role="examples">
4956
&reftitle.examples;
5057
<para>
@@ -77,13 +84,6 @@ $message = $socket->recv();
7784
</para>
7885
</refsect1>
7986

80-
<refsect1 role="returnvalues">
81-
&reftitle.returnvalues;
82-
<para>
83-
Throws ZMQContextException if context initialization fails.
84-
</para>
85-
</refsect1>
86-
8787
</refentry>
8888

8989
<!-- Keep this comment at the end of the file

‎reference/zmq/zmqcontext/getsocket.xml

Lines changed: 15 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,21 @@
5454
</variablelist>
5555
</para>
5656
</refsect1>
57-
57+
58+
<refsect1 role="returnvalues">
59+
&reftitle.returnvalues;
60+
<para>
61+
Returns a <classname>ZMQSocket</classname> object.
62+
</para>
63+
</refsect1>
64+
65+
<refsect1 role="errors">
66+
&reftitle.errors;
67+
<para>
68+
Throws <classname>ZMQSocketException</classname> on error.
69+
</para>
70+
</refsect1>
71+
5872
<refsect1 role="examples">
5973
&reftitle.examples;
6074
<para>
@@ -88,14 +102,6 @@ echo "Received message: {$message}\n";
88102
</para>
89103
</refsect1>
90104

91-
<refsect1 role="returnvalues">
92-
&reftitle.returnvalues;
93-
<para>
94-
Returns a ZMQSocket object on success. Throws ZMQSocketException on error.
95-
</para>
96-
</refsect1>
97-
98-
99105
</refentry>
100106

101107
<!-- Keep this comment at the end of the file

‎reference/zmq/zmqdevice/getidletimeout.xml

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,14 +18,18 @@
1818
</para>
1919
</refsect1>
2020

21+
<refsect1 role="parameters">
22+
&reftitle.parameters;
23+
&no.function.parameters;
24+
</refsect1>
25+
2126
<refsect1 role="returnvalues">
2227
&reftitle.returnvalues;
2328
<para>
2429
This method returns the idle callback timeout value.
2530
</para>
2631
</refsect1>
2732

28-
2933
</refentry>
3034

3135
<!-- Keep this comment at the end of the file

‎reference/zmq/zmqdevice/gettimertimeout.xml

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,14 +18,18 @@
1818
</para>
1919
</refsect1>
2020

21+
<refsect1 role="parameters">
22+
&reftitle.parameters;
23+
&no.function.parameters;
24+
</refsect1>
25+
2126
<refsect1 role="returnvalues">
2227
&reftitle.returnvalues;
2328
<para>
2429
This method returns the timer timeout value.
2530
</para>
2631
</refsect1>
2732

28-
2933
</refentry>
3034

3135
<!-- Keep this comment at the end of the file

‎reference/zmq/zmqpoll/poll.xml

Lines changed: 15 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,21 @@
5858
</variablelist>
5959
</para>
6060
</refsect1>
61-
61+
62+
<refsect1 role="returnvalues">
63+
&reftitle.returnvalues;
64+
<para>
65+
Returns an integer representing the amount of items with activity.
66+
</para>
67+
</refsect1>
68+
69+
<refsect1 role="errors">
70+
&reftitle.errors;
71+
<para>
72+
Throws <classname>ZMQPollException</classname> on error.
73+
</para>
74+
</refsect1>
75+
6276
<refsect1 role="examples">
6377
&reftitle.examples;
6478
<para>
@@ -134,14 +148,6 @@ while (true) {
134148
</para>
135149
</refsect1>
136150

137-
<refsect1 role="returnvalues">
138-
&reftitle.returnvalues;
139-
<para>
140-
Returns an integer representing amount of items with activity. Throws ZMQPollException on error.
141-
</para>
142-
</refsect1>
143-
144-
145151
</refentry>
146152

147153
<!-- Keep this comment at the end of the file

‎reference/zmq/zmqsocket/connect.xml

Lines changed: 15 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,21 @@
4343
</variablelist>
4444
</para>
4545
</refsect1>
46-
46+
47+
<refsect1 role="returnvalues">
48+
&reftitle.returnvalues;
49+
<para>
50+
Returns the current object.
51+
</para>
52+
</refsect1>
53+
54+
<refsect1 role="errors">
55+
&reftitle.errors;
56+
<para>
57+
Throws <classname>ZMQSocketException</classname> on error.
58+
</para>
59+
</refsect1>
60+
4761
<refsect1 role="examples">
4862
&reftitle.examples;
4963
<para>
@@ -84,14 +98,6 @@ echo "<p>Server said: {$message}</p>";
8498
</para>
8599
</refsect1>
86100

87-
<refsect1 role="returnvalues">
88-
&reftitle.returnvalues;
89-
<para>
90-
Returns the current object. Throws ZMQSocketException on error.
91-
</para>
92-
</refsect1>
93-
94-
95101
</refentry>
96102

97103
<!-- Keep this comment at the end of the file

‎reference/zmq/zmqsocket/construct.xml

Lines changed: 25 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -60,21 +60,33 @@
6060
Callback function, which is executed when a new socket structure is created. This function does not get invoked
6161
if the underlying persistent connection is re-used.
6262
</para>
63+
<methodsynopsis>
64+
<methodname><replaceable>callback</replaceable></methodname>
65+
<methodparam><type>ZMQSocket</type><parameter>socket</parameter></methodparam>
66+
<methodparam choice="opt"><type>string</type><parameter>persistent_id</parameter><initializer>&null;</initializer></methodparam>
67+
</methodsynopsis>
6368
</listitem>
6469
</varlistentry>
6570
</variablelist>
6671
</para>
6772
</refsect1>
68-
69-
<refsect1 role="examples">
70-
&reftitle.examples;
71-
<para>
72-
<example>
73-
<title>A <function>ZMQSocket</function> example</title>
74-
<para>
75-
Using callback the bind/connect socket
76-
</para>
77-
<programlisting role="php">
73+
74+
<refsect1 role="returnvalues">
75+
&reftitle.returnvalues;
76+
<para>
77+
Throws <classname>ZMQSocketException</classname> on error.
78+
</para>
79+
</refsect1>
80+
81+
<refsect1 role="examples">
82+
&reftitle.examples;
83+
<para>
84+
<example>
85+
<title>A <function>ZMQSocket</function> example</title>
86+
<para>
87+
Using callback the bind/connect socket
88+
</para>
89+
<programlisting role="php">
7890
<![CDATA[
7991
<?php
8092
@@ -101,29 +113,10 @@ $message = $socket->recv();
101113
echo "Received message: {$message}\n";
102114
?>
103115
]]>
104-
</programlisting>
105-
</example>
106-
</para>
107-
</refsect1>
108-
109-
<refsect1 role="notes">
110-
<para>
111-
The callback signature
112-
<note>
113-
<para>
114-
function on_new_socket_cb(ZMQSocket $socket, string $persistent_id = null);
115-
</para>
116-
</note>
117-
</para>
118-
</refsect1>
119-
120-
<refsect1 role="returnvalues">
121-
&reftitle.returnvalues;
122-
<para>
123-
Throws ZMQSocketException on error.
116+
</programlisting>
117+
</example>
124118
</para>
125-
</refsect1>
126-
119+
</refsect1>
127120

128121
</refentry>
129122

‎reference/zmq/zmqsocket/recv.xml

Lines changed: 16 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,22 @@
3737
</variablelist>
3838
</para>
3939
</refsect1>
40-
40+
41+
<refsect1 role="returnvalues">
42+
&reftitle.returnvalues;
43+
<para>
44+
Returns the message. If <constant>ZMQ::MODE_DONTWAIT</constant>
45+
is used and the operation would block &false; shall be returned.
46+
</para>
47+
</refsect1>
48+
49+
<refsect1 role="errors">
50+
&reftitle.errors;
51+
<para>
52+
Throws <classname>ZMQSocketException</classname> on error.
53+
</para>
54+
</refsect1>
55+
4156
<refsect1 role="examples">
4257
&reftitle.examples;
4358
<para>
@@ -96,16 +111,6 @@ Got response: This is a message
96111
</para>
97112
</refsect1>
98113

99-
<refsect1 role="returnvalues">
100-
&reftitle.returnvalues;
101-
<para>
102-
Returns the message. Throws ZMQSocketException in error.
103-
If <constant>ZMQ::MODE_DONTWAIT</constant> is used and the operation would
104-
block &boolean; false shall be returned.
105-
</para>
106-
</refsect1>
107-
108-
109114
</refentry>
110115

111116
<!-- Keep this comment at the end of the file

0 commit comments

Comments
 (0)