Skip to content

Commit d35c9a7

Browse files
ezimuelezimuel
committed
Fixed empty doc for API references
1 parent dbe1fd6 commit d35c9a7

File tree

5 files changed

+128
-27
lines changed

5 files changed

+128
-27
lines changed

‎src/Elasticsearch/ClientBuilder.php

Lines changed: 86 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -144,6 +144,9 @@ class ClientBuilder
144144
*/
145145
private $includePortInHostHeader = false;
146146

147+
/**
148+
* Create an instance of ClientBuilder
149+
*/
147150
public static function create(): ClientBuilder
148151
{
149152
return new static();
@@ -185,6 +188,7 @@ public function getRegisteredNamespacesBuilders(): array
185188
* Unknown keys will throw an exception by default, but this can be silenced
186189
* by setting `quiet` to true
187190
*
191+
* @param array $config
188192
* @param bool $quiet False if unknown settings throw exception, true to silently
189193
* ignore unknown settings
190194
* @throws Common\Exceptions\RuntimeException
@@ -214,6 +218,10 @@ public static function fromConfig(array $config, bool $quiet = false): Client
214218
}
215219

216220
/**
221+
* Get the default handler
222+
*
223+
* @param array $multiParams
224+
* @param array $singleParams
217225
* @throws \RuntimeException
218226
*/
219227
public static function defaultHandler(array $multiParams = [], array $singleParams = []): callable
@@ -235,6 +243,8 @@ public static function defaultHandler(array $multiParams = [], array $singlePara
235243
}
236244

237245
/**
246+
* Get the multi handler for async (CurlMultiHandler)
247+
*
238248
* @throws \RuntimeException
239249
*/
240250
public static function multiHandler(array $params = []): CurlMultiHandler
@@ -247,6 +257,8 @@ public static function multiHandler(array $params = []): CurlMultiHandler
247257
}
248258

249259
/**
260+
* Get the handler instance (CurlHandler)
261+
*
250262
* @throws \RuntimeException
251263
*/
252264
public static function singleHandler(): CurlHandler
@@ -258,6 +270,11 @@ public static function singleHandler(): CurlHandler
258270
}
259271
}
260272

273+
/**
274+
* Set connection Factory
275+
*
276+
* @param ConnectionFactoryInterface $connectionFactory
277+
*/
261278
public function setConnectionFactory(ConnectionFactoryInterface $connectionFactory): ClientBuilder
262279
{
263280
$this->connectionFactory = $connectionFactory;
@@ -266,7 +283,10 @@ public function setConnectionFactory(ConnectionFactoryInterface $connectionFacto
266283
}
267284

268285
/**
286+
* Set the connection pool (default is StaticNoPingConnectionPool)
287+
*
269288
* @param AbstractConnectionPool|string $connectionPool
289+
* @param array $args
270290
* @throws \InvalidArgumentException
271291
*/
272292
public function setConnectionPool($connectionPool, array $args = []): ClientBuilder
@@ -283,20 +303,35 @@ public function setConnectionPool($connectionPool, array $args = []): ClientBuil
283303
return $this;
284304
}
285305

306+
/**
307+
* Set the endpoint
308+
*
309+
* @param callable $endpoint
310+
*/
286311
public function setEndpoint(callable $endpoint): ClientBuilder
287312
{
288313
$this->endpoint = $endpoint;
289314

290315
return $this;
291316
}
292317

318+
/**
319+
* Register namespace
320+
*
321+
* @param NamespaceBuilderInterface $namespaceBuilder
322+
*/
293323
public function registerNamespace(NamespaceBuilderInterface $namespaceBuilder): ClientBuilder
294324
{
295325
$this->registeredNamespacesBuilders[] = $namespaceBuilder;
296326

297327
return $this;
298328
}
299329

330+
/**
331+
* Set the transport
332+
*
333+
* @param Transport $transport
334+
*/
300335
public function setTransport(Transport $transport): ClientBuilder
301336
{
302337
$this->transport = $transport;
@@ -305,8 +340,9 @@ public function setTransport(Transport $transport): ClientBuilder
305340
}
306341

307342
/**
343+
* Set the HTTP handler (cURL is default)
344+
*
308345
* @param mixed $handler
309-
* @return $this
310346
*/
311347
public function setHandler($handler): ClientBuilder
312348
{
@@ -315,13 +351,23 @@ public function setHandler($handler): ClientBuilder
315351
return $this;
316352
}
317353

354+
/**
355+
* Set the PSR-3 Logger
356+
*
357+
* @param LoggerInterface $logger
358+
*/
318359
public function setLogger(LoggerInterface $logger): ClientBuilder
319360
{
320361
$this->logger = $logger;
321362

322363
return $this;
323364
}
324365

366+
/**
367+
* Set the PSR-3 tracer
368+
*
369+
* @param LoggerInterface $tracer
370+
*/
325371
public function setTracer(LoggerInterface $tracer): ClientBuilder
326372
{
327373
$this->tracer = $tracer;
@@ -330,6 +376,8 @@ public function setTracer(LoggerInterface $tracer): ClientBuilder
330376
}
331377

332378
/**
379+
* Set the serializer
380+
*
333381
* @param \Elasticsearch\Serializers\SerializerInterface|string $serializer
334382
*/
335383
public function setSerializer($serializer): ClientBuilder
@@ -339,6 +387,11 @@ public function setSerializer($serializer): ClientBuilder
339387
return $this;
340388
}
341389

390+
/**
391+
* Set the hosts (nodes)
392+
*
393+
* @param array $hosts
394+
*/
342395
public function setHosts(array $hosts): ClientBuilder
343396
{
344397
$this->hosts = $hosts;
@@ -365,8 +418,9 @@ public function setApiKey(string $id, string $apiKey): ClientBuilder
365418
}
366419

367420
/**
368-
* Set the APIKey Pair, consiting of the API Id and the ApiKey of the Response from /_security/api_key
421+
* Set Basic access authentication
369422
*
423+
* @see https://en.wikipedia.org/wiki/Basic_access_authentication
370424
* @param string $username
371425
* @param string $password
372426
*
@@ -416,13 +470,23 @@ public function setElasticCloudId(string $cloudId): ClientBuilder
416470
return $this;
417471
}
418472

473+
/**
474+
* Set connection parameters
475+
*
476+
* @param array $params
477+
*/
419478
public function setConnectionParams(array $params): ClientBuilder
420479
{
421480
$this->connectionParams = $params;
422481

423482
return $this;
424483
}
425484

485+
/**
486+
* Set number or retries (default is equal to number of nodes)
487+
*
488+
* @param int $retries
489+
*/
426490
public function setRetries(int $retries): ClientBuilder
427491
{
428492
$this->retries = $retries;
@@ -431,6 +495,8 @@ public function setRetries(int $retries): ClientBuilder
431495
}
432496

433497
/**
498+
* Set the selector algorithm
499+
*
434500
* @param \Elasticsearch\ConnectionPool\Selectors\SelectorInterface|string $selector
435501
*/
436502
public function setSelector($selector): ClientBuilder
@@ -440,6 +506,12 @@ public function setSelector($selector): ClientBuilder
440506
return $this;
441507
}
442508

509+
/**
510+
* Set sniff on start
511+
*
512+
* @param bool $sniffOnStart enable or disable sniff on start
513+
*/
514+
443515
public function setSniffOnStart(bool $sniffOnStart): ClientBuilder
444516
{
445517
$this->sniffOnStart = $sniffOnStart;
@@ -448,7 +520,10 @@ public function setSniffOnStart(bool $sniffOnStart): ClientBuilder
448520
}
449521

450522
/**
523+
* Set SSL certificate
524+
*
451525
* @param string $cert The name of a file containing a PEM formatted certificate.
526+
* @param string $password if the certificate requires a password
452527
*/
453528
public function setSSLCert(string $cert, string $password = null): ClientBuilder
454529
{
@@ -458,7 +533,10 @@ public function setSSLCert(string $cert, string $password = null): ClientBuilder
458533
}
459534

460535
/**
461-
* @param string $key The name of a file containing a private SSL key.
536+
* Set SSL key
537+
*
538+
* @param string $key The name of a file containing a private SSL key
539+
* @param string $password if the private key requires a password
462540
*/
463541
public function setSSLKey(string $key, string $password = null): ClientBuilder
464542
{
@@ -468,6 +546,8 @@ public function setSSLKey(string $key, string $password = null): ClientBuilder
468546
}
469547

470548
/**
549+
* Set SSL verification
550+
*
471551
* @param bool|string $value
472552
*/
473553
public function setSSLVerification($value = true): ClientBuilder
@@ -499,6 +579,9 @@ public function includePortInHostHeader(bool $enable): ClientBuilder
499579
return $this;
500580
}
501581

582+
/**
583+
* Build and returns the Client object
584+
*/
502585
public function build(): Client
503586
{
504587
$this->buildLoggers();

‎util/docstheme/macros.twig

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -136,3 +136,35 @@ class
136136
{% if member.static %} static{% endif %}
137137
{% endspaceless %}
138138
{%- endmacro -%}
139+
140+
{% macro method_parameters_signature(method) -%}
141+
{%- from "macros.twig" import hint_link -%}
142+
(
143+
{%- for parameter in method.parameters %}
144+
{%- if parameter.hashint %}{{ hint_link(parameter.hint) }} {% endif -%}
145+
{%- if parameter.variadic %}...{% endif %}${{ parameter.name|raw }}
146+
{%- if parameter.default is not null %} = {{ parameter.default }}{% endif %}
147+
{%- if not loop.last %}, {% endif %}
148+
{%- endfor -%}
149+
)
150+
{%- endmacro %}
151+
152+
{% macro hint_link(hints) -%}
153+
{%- from _self import class_link %}
154+
155+
{%- if hints %}
156+
{%- for hint in hints %}
157+
{%- if hint.class %}
158+
{{- class_link(hint.name) }}
159+
{%- elseif hint.name %}
160+
{{- abbr_class(hint.name) }}
161+
{%- endif %}
162+
{%- if hint.array %}[]{% endif %}
163+
{%- if not loop.last %}|{% endif %}
164+
{%- endfor %}
165+
{%- endif %}
166+
{%- endmacro %}
167+
168+
{% macro class_link(class, absolute) -%}
169+
{{- class }}
170+
{%- endmacro %}

‎util/docstheme/pages/class.twig

Lines changed: 5 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -36,9 +36,8 @@ The {{ class_type(class) }} defines the following methods:
3636
{% if method.name != "__construct" %}
3737

3838

39-
{% if class.shortname != "ClientBuilder" %}
4039
[[{{ sanitize(replace_backslash(method)~"_"~method.name) }}]]
41-
.`{{ method.name }}()`
40+
.`{{ method.name }}{{ block('method_parameters_signature') }}`
4241
{% if method.tags('note') %}
4342
{% for note in method.tags('note') %}
4443
*NOTE:* {{ note|join(' ') }}
@@ -52,34 +51,16 @@ The {{ class_type(class) }} defines the following methods:
5251
{{ method.shortdesc|raw }}
5352
{% endif %}
5453
*/
55-
56-
$params = [
57-
// ...
58-
];
59-
60-
$client = ClientBuilder::create()->build();
61-
$response = {{ get_namespace(class) }}->{{ method.name }}({{ param_list(method)|trim(',') }});
62-
----
63-
****
64-
{% else %}
65-
[[{{ sanitize(replace_backslash(method)~"_"~method.name) }}]]
66-
.`{{ method.name }}()`
67-
****
68-
[source,php]
69-
----
70-
/*
71-
{% if method.shortdesc %}
72-
{{ method.shortdesc|raw }}
73-
{% endif %}
74-
*/
75-
7654
----
7755
****
7856
{% endif %}
79-
{% endif %}
8057

8158
{% endfor %}
8259
{% endif %}
8360

8461
{% endblock %}
8562

63+
{% block method_parameters_signature -%}
64+
{%- from "macros.twig" import method_parameters_signature -%}
65+
{{ method_parameters_signature(method) }}
66+
{%- endblock %}

‎util/template/client-class

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,8 @@ class Client
8989
}
9090

9191
/**
92+
* Extract an argument from the array of parameters
93+
*
9294
* @return null|mixed
9395
*/
9496
public function extractArgument(array &$params, string $arg)

‎util/template/client-namespace-function

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
/**
2+
* Returns the :name namespace
3+
*/
14
public function :name(): :namespace
25
{
36
return $this->:name;

0 commit comments

Comments
 (0)