From 6a7708447f4c78fced5064d2d4621b6f5d00c668 Mon Sep 17 00:00:00 2001 From: mondrake Date: Sun, 20 Oct 2024 17:53:35 +0200 Subject: [PATCH] More documentation tuning --- .github/workflows/code-docs.yml | 4 +-- src/ExtensionInterface.php | 8 +++-- src/TypeInterface.php | 60 +++++++++++++++++++++++++++++++-- 3 files changed, 65 insertions(+), 7 deletions(-) diff --git a/.github/workflows/code-docs.yml b/.github/workflows/code-docs.yml index 94b072bc..9df991ce 100644 --- a/.github/workflows/code-docs.yml +++ b/.github/workflows/code-docs.yml @@ -3,8 +3,6 @@ name: Code documentation on: push: branches: [ master ] - pull_request: - branches: [ master ] # Allow running the workflow manually from the Actions tab #workflow_dispatch: @@ -37,7 +35,7 @@ jobs: restore-keys: | ${{ runner.os }}-phpdocumentor- - name: Build with phpDocumentor - run: docker run --rm --volume "$(pwd):/data" phpdoc/phpdoc:3 -vv -d src --target docs --cache-folder .phpdoc/cache --template default --visibility api --title MimeMap + run: docker run --rm --volume "$(pwd):/data" phpdoc/phpdoc:3 -vv -d src --target docs --cache-folder .phpdoc/cache --template default --title MimeMap - name: Upload artifact to GitHub Pages uses: actions/upload-pages-artifact@v3 with: diff --git a/src/ExtensionInterface.php b/src/ExtensionInterface.php index a952d69d..71b6c2e8 100644 --- a/src/ExtensionInterface.php +++ b/src/ExtensionInterface.php @@ -6,8 +6,6 @@ /** * Interface for Extension objects. - * - * @api */ interface ExtensionInterface { @@ -18,6 +16,8 @@ interface ExtensionInterface * A file extension. * @param class-string|null $mapClass * (Optional) The FQCN of the map class to use. + * + * @api */ public function __construct(string $extension, ?string $mapClass = null); @@ -25,6 +25,8 @@ public function __construct(string $extension, ?string $mapClass = null); * Returns the file extension's preferred MIME type. * * @throws MappingException if no mapping found. + * + * @api */ public function getDefaultType(): string; @@ -34,6 +36,8 @@ public function getDefaultType(): string; * @throws MappingException if no mapping found. * * @return list + * + * @api */ public function getTypes(): array; } diff --git a/src/TypeInterface.php b/src/TypeInterface.php index 98596a7a..e251131f 100644 --- a/src/TypeInterface.php +++ b/src/TypeInterface.php @@ -6,8 +6,6 @@ /** * Interface for Type objects. - * - * @api */ interface TypeInterface { @@ -20,6 +18,8 @@ interface TypeInterface * MIME type string to be parsed. * @param class-string|null $mapClass * (Optional) The FQCN of the map class to use. + * + * @api */ public function __construct(string $typeString, ?string $mapClass = null); @@ -27,16 +27,22 @@ public function __construct(string $typeString, ?string $mapClass = null); * Gets a MIME type's media. * * Note: 'media' refers to the portion before the first slash. + * + * @api */ public function getMedia(): string; /** * Sets a MIME type's media. + * + * @api */ public function setMedia(string $media): TypeInterface; /** * Checks if the MIME type has media comment. + * + * @api */ public function hasMediaComment(): bool; @@ -44,6 +50,8 @@ public function hasMediaComment(): bool; * Gets the MIME type's media comment. * * @throws UndefinedException + * + * @api */ public function getMediaComment(): string; @@ -51,21 +59,29 @@ public function getMediaComment(): string; * Sets the MIME type's media comment. * * @param string $comment (optional) a comment; when missing any existing comment is removed. + * + * @api */ public function setMediaComment(?string $comment = null): TypeInterface; /** * Gets a MIME type's subtype. + * + * @api */ public function getSubType(): string; /** * Sets a MIME type's subtype. + * + * @api */ public function setSubType(string $subType): TypeInterface; /** * Checks if the MIME type has subtype comment. + * + * @api */ public function hasSubTypeComment(): bool; @@ -73,6 +89,8 @@ public function hasSubTypeComment(): bool; * Gets the MIME type's subtype comment. * * @throws UndefinedException + * + * @api */ public function getSubTypeComment(): string; @@ -80,11 +98,15 @@ public function getSubTypeComment(): string; * Sets the MIME type's subtype comment. * * @param string|null $comment (optional) a comment; when missing any existing comment is removed. + * + * @api */ public function setSubTypeComment(?string $comment = null): TypeInterface; /** * Checks if the MIME type has any parameter. + * + * @api */ public function hasParameters(): bool; @@ -94,6 +116,8 @@ public function hasParameters(): bool; * @return TypeParameter[] * * @throws UndefinedException + * + * @api */ public function getParameters(): array; @@ -101,6 +125,8 @@ public function getParameters(): array; * Checks if the MIME type has a parameter. * * @throws UndefinedException + * + * @api */ public function hasParameter(string $name): bool; @@ -108,16 +134,22 @@ public function hasParameter(string $name): bool; * Get a MIME type's parameter. * * @throws UndefinedException + * + * @api */ public function getParameter(string $name): TypeParameter; /** * Add a parameter to this type + * + * @api */ public function addParameter(string $name, string $value, ?string $comment = null): void; /** * Remove a parameter from this type. + * + * @api */ public function removeParameter(string $name): void; @@ -128,6 +160,8 @@ public function removeParameter(string $name): void; * * @param int $format * The format of the output string. + * + * @api */ public function toString(int $format = Type::FULL_TEXT): string; @@ -136,6 +170,8 @@ public function toString(int $format = Type::FULL_TEXT): string; * * Note: Experimental types are denoted by a leading 'x-' in the media or * subtype, e.g. text/x-vcard or x-world/x-vrml. + * + * @api */ public function isExperimental(): bool; @@ -143,16 +179,22 @@ public function isExperimental(): bool; * Is this a vendor MIME type? * * Note: Vendor types are denoted with a leading 'vnd. in the subtype. + * + * @api */ public function isVendor(): bool; /** * Is this a wildcard type? + * + * @api */ public function isWildcard(): bool; /** * Is this an alias? + * + * @api */ public function isAlias(): bool; @@ -168,6 +210,8 @@ public function isAlias(): bool; * * @return bool * True if there was a match, false otherwise. + * + * @api */ public function wildcardMatch(string $wildcard): bool; @@ -180,11 +224,15 @@ public function wildcardMatch(string $wildcard): bool; * @throws MappingException if no mapping found. * * @return array + * + * @api */ public function buildTypesList(): array; /** * Checks if a description for the MIME type exists. + * + * @api */ public function hasDescription(): bool; @@ -197,6 +245,8 @@ public function hasDescription(): bool; * appended with a comma. Defaults to false. * * @throws MappingException if no description found. + * + * @api */ public function getDescription(bool $includeAcronym = false): string; @@ -209,6 +259,8 @@ public function getDescription(bool $includeAcronym = false): string; * @throws MappingException on error. * * @return list + * + * @api */ public function getAliases(): array; @@ -216,6 +268,8 @@ public function getAliases(): array; * Returns the MIME type's preferred file extension. * * @throws MappingException if no mapping found. + * + * @api */ public function getDefaultExtension(): string; @@ -227,6 +281,8 @@ public function getDefaultExtension(): string; * @throws MappingException if no mapping found. * * @return list + * + * @api */ public function getExtensions(): array; }