Skip to content

Commit 71ec361

Browse files
dirxdirx
committed
Update low level api docs generation
1 parent f1d1d09 commit 71ec361

File tree

2 files changed

+64
-57
lines changed

2 files changed

+64
-57
lines changed

‎resources/ffigen/LibrdkafkaDocumentation.php

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,29 @@ public function extract(): void
2727
$page = new Crawler($html);
2828
$elements = $page->filter('div[class=contents] a[id]')->each(
2929
function (Crawler $node, $i) {
30+
// rewrite code examples - use pre & code tag
31+
$node->nextAll()->eq(1)->filter('div[class=fragment]')->each(
32+
function (Crawler $node, $i) {
33+
// remove ttc nodes
34+
$node->filter('div[class=ttc]')->each(function (Crawler $node, $i) {
35+
$node->getNode(0)->parentNode->removeChild($node->getNode(0));
36+
});
37+
38+
$oldNode = $node->first()->getNode(0);
39+
$doc = $oldNode->ownerDocument;
40+
41+
$content = $oldNode->ownerDocument->createTextNode(trim($node->first()->text('', false)));
42+
$code = $doc->createElement('code');
43+
$code->append($content);
44+
$pre = $doc->createElement('pre');
45+
$pre->append($code);
46+
$newNode = $doc->createElement('div');
47+
$newNode->append($pre);
48+
49+
$oldNode->parentNode->replaceChild($newNode, $oldNode);
50+
}
51+
);
52+
3053
// extract defines & methods
3154
if ($node->nextAll()->count()
3255
&& $node->nextAll()->eq(1)->filter('td[class=memname]')->count()

‎src/RdKafka/FFI/Methods.php

Lines changed: 41 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -565,22 +565,16 @@ public static function rd_kafka_message_status(?\FFI\CData $rkmessage): int
565565

566566
/**
567567
* <p>Create configuration object. </p>
568-
* <p>When providing your own configuration to the <code>rd_kafka_*_new_*</code>() calls the rd_kafka_conf_t objects needs to be created with this function which will set up the defaults. I.e.: </p><div class="fragment"><div class="line">rd_kafka_conf_t *myconf;</div>
569-
* <div class="line">rd_kafka_conf_res_t res;</div>
570-
* <div class="line"> </div>
571-
* <div class="line">myconf = rd_kafka_conf_new();</div>
572-
* <div class="line">res = rd_kafka_conf_set(myconf, <span class="stringliteral">"socket.timeout.ms"</span>, <span class="stringliteral">"600"</span>,</div>
573-
* <div class="line"> errstr, <span class="keyword">sizeof</span>(errstr));</div>
574-
* <div class="line"><span class="keywordflow">if</span> (res != RD_KAFKA_CONF_OK)</div>
575-
* <div class="line"> die(<span class="stringliteral">"%s\n"</span>, errstr);</div>
576-
* <div class="line"> </div>
577-
* <div class="line">rk = rd_kafka_new(..., myconf);</div>
578-
* <div class="ttc" id="ardkafka_8h_html_a63d5cd86ab1f77772b2be170e1c09c24"><div class="ttname">rd_kafka_new</div><div class="ttdeci">RD_EXPORT rd_kafka_t * rd_kafka_new(rd_kafka_type_t type, rd_kafka_conf_t *conf, char *errstr, size_t errstr_size)</div><div class="ttdoc">Creates a new Kafka handle and starts its operation according to the specified type (RD_KAFKA_CONSUME...</div></div>
579-
* <div class="ttc" id="ardkafka_8h_html_aa7459bd22e8cfa81aa8c2480a4a0304c"><div class="ttname">rd_kafka_conf_new</div><div class="ttdeci">RD_EXPORT rd_kafka_conf_t * rd_kafka_conf_new(void)</div><div class="ttdoc">Create configuration object.</div></div>
580-
* <div class="ttc" id="ardkafka_8h_html_abb1b319278333e8cdee9442da7f135e8"><div class="ttname">rd_kafka_conf_set</div><div class="ttdeci">RD_EXPORT rd_kafka_conf_res_t rd_kafka_conf_set(rd_kafka_conf_t *conf, const char *name, const char *value, char *errstr, size_t errstr_size)</div><div class="ttdoc">Sets a configuration property.</div></div>
581-
* <div class="ttc" id="ardkafka_8h_html_ad8306a08e59e8e2cbc6abdb84f9689f4"><div class="ttname">rd_kafka_conf_res_t</div><div class="ttdeci">rd_kafka_conf_res_t</div><div class="ttdoc">Configuration result type.</div><div class="ttdef"><b>Definition:</b> rdkafka.h:1603</div></div>
582-
* <div class="ttc" id="ardkafka_8h_html_ad8306a08e59e8e2cbc6abdb84f9689f4a12343fa082ab52164a17130d6b0d0f5b"><div class="ttname">RD_KAFKA_CONF_OK</div><div class="ttdeci">@ RD_KAFKA_CONF_OK</div><div class="ttdef"><b>Definition:</b> rdkafka.h:1608</div></div>
583-
* </div><!-- fragment --><p>Please see CONFIGURATION.md for the default settings or use rd_kafka_conf_properties_show() to provide the information at runtime.</p>
568+
* <p>When providing your own configuration to the <code>rd_kafka_*_new_*</code>() calls the rd_kafka_conf_t objects needs to be created with this function which will set up the defaults. I.e.: </p><div><pre><code>rd_kafka_conf_t *myconf;
569+
* rd_kafka_conf_res_t res;
570+
*
571+
* myconf = rd_kafka_conf_new();
572+
* res = rd_kafka_conf_set(myconf, "socket.timeout.ms", "600",
573+
* errstr, sizeof(errstr));
574+
* if (res != RD_KAFKA_CONF_OK)
575+
* die("%s\n", errstr);
576+
*
577+
* rk = rd_kafka_new(..., myconf);</code></pre></div><!-- fragment --><p>Please see CONFIGURATION.md for the default settings or use rd_kafka_conf_properties_show() to provide the information at runtime.</p>
584578
* <p>The properties are identical to the Apache Kafka configuration properties whenever possible.</p>
585579
* <dl class="section remark"><dt>Remarks</dt><dd>A successful call to rd_kafka_new() will assume ownership of the conf object and rd_kafka_conf_destroy() must not be called.</dd></dl>
586580
*
@@ -748,47 +742,37 @@ public static function rd_kafka_conf_set_consume_cb(?\FFI\CData $conf, $consume_
748742
* rd_kafka_assignment_lost() </dd>
749743
* <dd>
750744
* rd_kafka_rebalance_protocol()</dd></dl>
751-
* <p>The following example shows the application's responsibilities: </p><div class="fragment"><div class="line"><span class="keyword">static</span> <span class="keywordtype">void</span> rebalance_cb (rd_kafka_t *rk, rd_kafka_resp_err_t err,</div>
752-
* <div class="line"> rd_kafka_topic_partition_list_t *partitions,</div>
753-
* <div class="line"> <span class="keywordtype">void</span> *opaque) {</div>
754-
* <div class="line"> </div>
755-
* <div class="line"> <span class="keywordflow">switch</span> (err)</div>
756-
* <div class="line"> {</div>
757-
* <div class="line"> <span class="keywordflow">case</span> RD_KAFKA_RESP_ERR__ASSIGN_PARTITIONS:</div>
758-
* <div class="line"> <span class="comment">// application may load offets from arbitrary external</span></div>
759-
* <div class="line"> <span class="comment">// storage here and update \p partitions</span></div>
760-
* <div class="line"> <span class="keywordflow">if</span> (!strcmp(rd_kafka_rebalance_protocol(rk), <span class="stringliteral">"COOPERATIVE"</span>))</div>
761-
* <div class="line"> rd_kafka_incremental_assign(rk, partitions);</div>
762-
* <div class="line"> <span class="keywordflow">else</span> <span class="comment">// EAGER</span></div>
763-
* <div class="line"> rd_kafka_assign(rk, partitions);</div>
764-
* <div class="line"> <span class="keywordflow">break</span>;</div>
765-
* <div class="line"> </div>
766-
* <div class="line"> <span class="keywordflow">case</span> RD_KAFKA_RESP_ERR__REVOKE_PARTITIONS:</div>
767-
* <div class="line"> <span class="keywordflow">if</span> (manual_commits) <span class="comment">// Optional explicit manual commit</span></div>
768-
* <div class="line"> rd_kafka_commit(rk, partitions, 0); <span class="comment">// sync commit</span></div>
769-
* <div class="line"> </div>
770-
* <div class="line"> <span class="keywordflow">if</span> (!strcmp(rd_kafka_rebalance_protocol(rk), <span class="stringliteral">"COOPERATIVE"</span>))</div>
771-
* <div class="line"> rd_kafka_incremental_unassign(rk, partitions);</div>
772-
* <div class="line"> <span class="keywordflow">else</span> <span class="comment">// EAGER</span></div>
773-
* <div class="line"> rd_kafka_assign(rk, NULL);</div>
774-
* <div class="line"> <span class="keywordflow">break</span>;</div>
775-
* <div class="line"> </div>
776-
* <div class="line"> <span class="keywordflow">default</span>:</div>
777-
* <div class="line"> handle_unlikely_error(err);</div>
778-
* <div class="line"> rd_kafka_assign(rk, NULL); <span class="comment">// sync state</span></div>
779-
* <div class="line"> <span class="keywordflow">break</span>;</div>
780-
* <div class="line"> }</div>
781-
* <div class="line">}</div>
782-
* <div class="ttc" id="ardkafka_8h_html_a03509bab51072c72a8dcf52337e6d5cb"><div class="ttname">rd_kafka_resp_err_t</div><div class="ttdeci">rd_kafka_resp_err_t</div><div class="ttdoc">Error codes.</div><div class="ttdef"><b>Definition:</b> rdkafka.h:278</div></div>
783-
* <div class="ttc" id="ardkafka_8h_html_a03509bab51072c72a8dcf52337e6d5cba4eab145a6f57f455bdde22cb94b61e90"><div class="ttname">RD_KAFKA_RESP_ERR__ASSIGN_PARTITIONS</div><div class="ttdeci">@ RD_KAFKA_RESP_ERR__ASSIGN_PARTITIONS</div><div class="ttdef"><b>Definition:</b> rdkafka.h:334</div></div>
784-
* <div class="ttc" id="ardkafka_8h_html_a03509bab51072c72a8dcf52337e6d5cba52a7ba59b755f419beec0433cb1633bb"><div class="ttname">RD_KAFKA_RESP_ERR__REVOKE_PARTITIONS</div><div class="ttdeci">@ RD_KAFKA_RESP_ERR__REVOKE_PARTITIONS</div><div class="ttdef"><b>Definition:</b> rdkafka.h:336</div></div>
785-
* <div class="ttc" id="ardkafka_8h_html_a0566419eff2001f8371e3b50aa7d26e9"><div class="ttname">rd_kafka_assign</div><div class="ttdeci">RD_EXPORT rd_kafka_resp_err_t rd_kafka_assign(rd_kafka_t *rk, const rd_kafka_topic_partition_list_t *partitions)</div><div class="ttdoc">Atomic assignment of partitions to consume.</div></div>
786-
* <div class="ttc" id="ardkafka_8h_html_a27f7bd18e42ed44f33932c2f9b6a4192"><div class="ttname">rd_kafka_incremental_unassign</div><div class="ttdeci">RD_EXPORT rd_kafka_error_t * rd_kafka_incremental_unassign(rd_kafka_t *rk, const rd_kafka_topic_partition_list_t *partitions)</div><div class="ttdoc">Incrementally remove partitions from the current assignment.</div></div>
787-
* <div class="ttc" id="ardkafka_8h_html_a3bd9f42cf76b2a8cf2f4a4343abe8556"><div class="ttname">rd_kafka_incremental_assign</div><div class="ttdeci">RD_EXPORT rd_kafka_error_t * rd_kafka_incremental_assign(rd_kafka_t *rk, const rd_kafka_topic_partition_list_t *partitions)</div><div class="ttdoc">Incrementally add partitions to the current assignment.</div></div>
788-
* <div class="ttc" id="ardkafka_8h_html_a57d367712406848d59cdaae97ab29354"><div class="ttname">rd_kafka_rebalance_protocol</div><div class="ttdeci">RD_EXPORT const char * rd_kafka_rebalance_protocol(rd_kafka_t *rk)</div><div class="ttdoc">The rebalance protocol currently in use. This will be "NONE" if the consumer has not (yet) joined a g...</div></div>
789-
* <div class="ttc" id="ardkafka_8h_html_ab96539928328f14c3c9177ea0c896c87"><div class="ttname">rd_kafka_commit</div><div class="ttdeci">RD_EXPORT rd_kafka_resp_err_t rd_kafka_commit(rd_kafka_t *rk, const rd_kafka_topic_partition_list_t *offsets, int async)</div><div class="ttdoc">Commit offsets on broker for the provided list of partitions.</div></div>
790-
* <div class="ttc" id="astructrd__kafka__topic__partition__list__t_html"><div class="ttname">rd_kafka_topic_partition_list_t</div><div class="ttdoc">A growable list of Topic+Partitions.</div><div class="ttdef"><b>Definition:</b> rdkafka.h:917</div></div>
791-
* </div><!-- fragment --><dl class="section remark"><dt>Remarks</dt><dd>The above example lacks error handling for assign calls, see the examples/ directory. </dd></dl>
745+
* <p>The following example shows the application's responsibilities: </p><div><pre><code>static void rebalance_cb (rd_kafka_t *rk, rd_kafka_resp_err_t err,
746+
* rd_kafka_topic_partition_list_t *partitions,
747+
* void *opaque) {
748+
*
749+
* switch (err)
750+
* {
751+
* case RD_KAFKA_RESP_ERR__ASSIGN_PARTITIONS:
752+
* // application may load offets from arbitrary external
753+
* // storage here and update \p partitions
754+
* if (!strcmp(rd_kafka_rebalance_protocol(rk), "COOPERATIVE"))
755+
* rd_kafka_incremental_assign(rk, partitions);
756+
* else // EAGER
757+
* rd_kafka_assign(rk, partitions);
758+
* break;
759+
*
760+
* case RD_KAFKA_RESP_ERR__REVOKE_PARTITIONS:
761+
* if (manual_commits) // Optional explicit manual commit
762+
* rd_kafka_commit(rk, partitions, 0); // sync commit
763+
*
764+
* if (!strcmp(rd_kafka_rebalance_protocol(rk), "COOPERATIVE"))
765+
* rd_kafka_incremental_unassign(rk, partitions);
766+
* else // EAGER
767+
* rd_kafka_assign(rk, NULL);
768+
* break;
769+
*
770+
* default:
771+
* handle_unlikely_error(err);
772+
* rd_kafka_assign(rk, NULL); // sync state
773+
* break;
774+
* }
775+
* }</code></pre></div><!-- fragment --><dl class="section remark"><dt>Remarks</dt><dd>The above example lacks error handling for assign calls, see the examples/ directory. </dd></dl>
792776
* @param \FFI\CData|null $conf rd_kafka_conf_t*
793777
* @param \FFI\CData|\Closure $rebalance_cb void(*)(rd_kafka_t*, rd_kafka_resp_err_t, rd_kafka_topic_partition_list_t*, void*)
794778
* @since 1.0.0 of librdkafka

0 commit comments

Comments
 (0)