Updated the documentation

src/Author.php

@@ -7,39 +7,31 @@
 /** Represents the author of a comment. */
 class Author implements \JsonSerializable {
 
-	/** @var string The author's mail address. */
+	/** The author's mail address. */
 	private string $email = "";
 
-	/** @var string The author's IP address. */
+	/** The author's IP address. */
 	private string $ipAddress;
 
-	/** @var string The author's name. */
+	/** The author's name. */
 	private string $name = "";
 
-	/** @var string The author's role. */
+	/** The author's role. */
 	private string $role = "";
 
-	/** @var UriInterface|null The URL of the author's website. */
+	/** The URL of the author's website. */
 	private ?UriInterface $url = null;
 
-	/** @var string The author's user agent, that is the string identifying the Web browser used to submit comments. */
+	/** The author's user agent, that is the string identifying the Web browser used to submit comments. */
 	private string $userAgent;
 
-	/**
-	 * Creates a new author.
-	 * @param string|null $ipAddress The author's IP address. Defaults to `$_SERVER["REMOTE_ADDR"]`.
-	 * @param string|null $userAgent The author's user agent. Defaults to `$_SERVER["HTTP_USER_AGENT"]`.
-	 */
+	/** Creates a new author. */
 	function __construct(?string $ipAddress = null, ?string $userAgent = null) {
 		$this->ipAddress = $ipAddress ?? ($_SERVER["REMOTE_ADDR"] ?? "");
 		$this->userAgent = $userAgent ?? ($_SERVER["HTTP_USER_AGENT"] ?? "");
 	}
 
-	/**
-	 * Creates a new author from the specified JSON object.
-	 * @param object $map A JSON object representing an author.
-	 * @return self The instance corresponding to the specified JSON object.
-	 */
+	/** Creates a new author from the specified JSON object. */
 	static function fromJson(object $map): self {
 		$author = new self(
 			isset($map->user_ip) && is_string($map->user_ip) ? $map->user_ip : "",
@@ -53,58 +45,37 @@ static function fromJson(object $map): self {
 			->setUrl(isset($map->comment_author_url) && is_string($map->comment_author_url) ? new Uri($map->comment_author_url) : null);
 	}
 
-	/**
-	 * Gets the author's mail address.
-	 * @return string The author's mail address.
-	 */
+	/** Gets the author's mail address. */
 	function getEmail(): string {
 		return $this->email;
 	}
 
-	/**
-	 * Gets the author's IP address.
-	 * @return string The author's IP address.
-	 */
+	/** Gets the author's IP address. */
 	function getIPAddress(): string {
 		return $this->ipAddress;
 	}
 
-	/**
-	 * Gets the author's name.
-	 * @return string The author's name.
-	 */
+	/** Gets the author's name. */
 	function getName(): string {
 		return $this->name;
 	}
 
-	/**
-	 * Gets the author's role.
-	 * @return string The author's role.
-	 */
+	/** Gets the author's role. */
 	function getRole(): string {
 		return $this->role;
 	}
 
-	/**
-	 * Gets the URL of the author's website.
-	 * @return UriInterface|null The URL of the author's website.
-	 */
+	/** Gets the URL of the author's website. */
 	function getUrl(): ?UriInterface {
 		return $this->url;
 	}
 
-	/**
-	 * Gets the author's user agent, that is the string identifying the Web browser used to submit comments.
-	 * @return string The author's user agent.
-	 */
+	/** Gets the author's user agent, that is the string identifying the Web browser used to submit comments. */
 	function getUserAgent(): string {
 		return $this->userAgent;
 	}
 
-	/**
-	 * Converts this object to a map in JSON format.
-	 * @return \stdClass The map in JSON format corresponding to this object.
-	 */
+	/** Converts this object to a map in JSON format. */
 	function jsonSerialize(): \stdClass {
 		$map = new \stdClass;
 		$map->user_agent = $this->getUserAgent();

src/Blog.php

@@ -7,59 +7,40 @@
 /** Represents the front page or home URL transmitted when making requests. */
 class Blog implements \JsonSerializable {
 
-	/** @var string The character encoding for the values included in comments. */
+	/** The character encoding for the values included in comments. */
 	private string $charset = "";
 
-	/** @var \ArrayObject<int, string> The languages in use on the blog or site, in ISO 639-1 format. */
+	/** The languages in use on the blog or site, in ISO 639-1 format. */
 	private \ArrayObject $languages;
 
-	/**
-	 * Creates a new blog.
-	 * @param UriInterface|null $url The blog or site URL.
-	 */
+	/** Creates a new blog. */
 	function __construct(private ?UriInterface $url) {
 		$this->languages = new \ArrayObject;
 	}
 
-	/**
-	 * Creates a new blog from the specified JSON object.
-	 * @param object $map A JSON object representing a blog.
-	 * @return self The instance corresponding to the specified JSON object.
-	 */
+	/** Creates a new blog from the specified JSON object. */
 	static function fromJson(object $map): self {
 		return (new self(isset($map->blog) && is_string($map->blog) ? new Uri($map->blog) : null))
 			->setCharset(isset($map->blog_charset) && is_string($map->blog_charset) ? $map->blog_charset : "")
 			->setLanguages(isset($map->blog_lang) && is_string($map->blog_lang) ? array_map("trim", explode(",", $map->blog_lang)) : []);
 	}
 
-	/**
-	 * Gets the character encoding for the values included in comments.
-	 * @return string The character encoding for the values included in comments.
-	 */
+	/** Gets the character encoding for the values included in comments. */
 	function getCharset(): string {
 		return $this->charset;
 	}
 
-	/**
-	 * Gets the languages in use on the blog or site, in ISO 639-1 format.
-	 * @return \ArrayObject<int, string> The languages in use on the blog or site.
-	 */
+	/** Gets the languages in use on the blog or site, in ISO 639-1 format. */
 	function getLanguages(): \ArrayObject {
 		return $this->languages;
 	}
 
-	/**
-	 * Gets the blog or site URL.
-	 * @return UriInterface|null The blog or site URL.
-	 */
+	/** Gets the blog or site URL. */
 	function getUrl(): ?UriInterface {
 		return $this->url;
 	}
 
-	/**
-	 * Converts this object to a map in JSON format.
-	 * @return \stdClass The map in JSON format corresponding to this object.
-	 */
+	/** Converts this object to a map in JSON format. */
 	function jsonSerialize(): \stdClass {
 		$map = new \stdClass;
 		$map->blog = (string) $this->getUrl();

src/CheckResult.php

@@ -4,12 +4,12 @@
 /** Specifies the result of a comment check. */
 abstract class CheckResult {
 
-	/** @var string The comment is not a spam (i.e. a ham). */
+	/** The comment is not a spam (i.e. a ham). */
 	const isHam = "isHam";
 
-	/** @var string The comment is a pervasive spam (i.e. it can be safely discarded). */
+	/** The comment is a pervasive spam (i.e. it can be safely discarded). */
 	const isPervasiveSpam = "isPervasiveSpam";
 
-	/** @var string The comment is a spam. */
+	/** The comment is a spam. */
 	const isSpam = "isSpam";
 }

src/Client.php

@@ -8,29 +8,25 @@
 /** Submits comments to the [Akismet](https://akismet.com) service. */
 class Client extends EventDispatcher {
 
-	/** @var string An event that is triggered when a request is made to the remote service. */
+	/** An event that is triggered when a request is made to the remote service. */
 	const eventRequest = RequestEvent::class;
 
-	/** @var string An event that is triggered when a response is received from the remote service. */
+	/** An event that is triggered when a response is received from the remote service. */
 	const eventResponse = ResponseEvent::class;
 
-	/** @var UriInterface The URL of the API end point. */
+	/** The URL of the API end point. */
 	private UriInterface $endPoint;
 
-	/** @var Psr18Client The HTTP client. */
+	/** The HTTP client. */
 	private Psr18Client $http;
 
-	/** @var bool Value indicating whether the client operates in test mode. */
+	/** Value indicating whether the client operates in test mode. */
 	private bool $isTest = false;
 
-	/** @var string The user agent string to use when making requests. */
+	/** The user agent string to use when making requests. */
 	private string $userAgent;
 
-	/**
-	 * Creates a new client.
-	 * @param string $apiKey The Akismet API key.
-	 * @param Blog $blog The front page or home URL of the instance making requests.
-	 */
+	/** Creates a new client. */
 	function __construct(private string $apiKey, private Blog $blog) {
 		parent::__construct();
 
@@ -44,11 +40,7 @@ function __construct(private string $apiKey, private Blog $blog) {
 		$this->userAgent = "PHP/$phpVersion | Akismet/$pkgVersion";
 	}
 
-	/**
-	 * Checks the specified comment against the service database, and returns a value indicating whether it is spam.
-	 * @param Comment $comment The comment to be checked.
-	 * @return string A `CheckResult` value indicating whether the specified comment is spam.
-	 */
+	/** Checks the specified comment against the service database, and returns a value indicating whether it is spam. */
 	function checkComment(Comment $comment): string {
 		$apiUrl = $this->getEndPoint();
 		$endPoint = $this->http->createUri("{$apiUrl->getScheme()}://{$this->getApiKey()}.{$apiUrl->getAuthority()}{$apiUrl->getPath()}comment-check");
@@ -58,43 +50,30 @@ function checkComment(Comment $comment): string {
 		return $response->getHeaderLine("X-akismet-pro-tip") == "discard" ? CheckResult::isPervasiveSpam : CheckResult::isSpam;
 	}
 
-	/**
-	 * Gets the Akismet API key.
-	 * @return string The Akismet API key.
-	 */
+	/** Gets the Akismet API key. */
 	function getApiKey(): string {
 		return $this->apiKey;
 	}
 
-	/**
-	 * Gets the front page or home URL of the instance making requests.
-	 * @return Blog The front page or home URL.
-	 */
+	/** Gets the front page or home URL of the instance making requests. */
 	function getBlog(): Blog {
 		return $this->blog;
 	}
 
-	/**
-	 * Gets the URL of the API end point.
-	 * @return UriInterface The URL of the API end point.
-	 */
+	/** Gets the URL of the API end point. */
 	function getEndPoint(): UriInterface {
 		return $this->endPoint;
 	}
 
 	/**
 	 * Gets the user agent string to use when making requests.
 	 * If possible, the user agent string should always have the following format: `Application Name/Version | Plugin Name/Version`.
-	 * @return string The user agent string to use when making requests.
 	 */
 	function getUserAgent(): string {
 		return $this->userAgent;
 	}
 
-	/**
-	 * Gets a value indicating whether the client operates in test mode.
-	 * @return bool `true` if the client operates in test mode, otherwise `false`.
-	 */
+	/** Gets a value indicating whether the client operates in test mode. */
 	function isTest(): bool {
 		return $this->isTest;
 	}
@@ -162,10 +141,7 @@ function verifyKey(): bool {
 	}
 
 	/**
-	 * Queries the service by posting the specified fields to a given end point, and returns the response as a string.
-	 * @param UriInterface $endPoint The URL of the end point to query.
-	 * @param array<string, string> $fields The fields describing the query body.
-	 * @return ResponseInterface The server response.
+	 * Queries the service by posting the specified fields to a given end point, and returns the server response.
 	 * @throws ClientException An error occurred while querying the end point.
 	 */
 	private function fetch(UriInterface $endPoint, array $fields = []): ResponseInterface {

src/ClientException.php

@@ -6,20 +6,12 @@
 /** An exception caused by an error in a `Client` request. */
 class ClientException extends \RuntimeException {
 
-	/**
-	 * Creates a new client exception.
-	 * @param string $message A message describing the error.
-	 * @param UriInterface|null $uri The URL of the HTTP request or response that failed.
-	 * @param \Throwable|null $previous The previous exception used for the exception chaining.
-	 */
+	/** Creates a new client exception. */
 	function __construct(string $message, private ?UriInterface $uri = null, ?\Throwable $previous = null) {
 		parent::__construct($message, 0, $previous);
 	}
 
-	/**
-	 * Gets the URL of the HTTP request or response that failed.
-	 * @return UriInterface|null The URL of the HTTP request or response that failed.
-	 */
+	/** Gets the URL of the HTTP request or response that failed. */
 	function getUri(): ?UriInterface {
 		return $this->uri;
 	}