More documentation tuning

Author: mondrake

.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:

src/ExtensionInterface.php

@@ -6,8 +6,6 @@
 
 /**
  * Interface for Extension objects.
- *
- * @api
  */
 interface ExtensionInterface
 {
@@ -18,13 +16,17 @@ interface ExtensionInterface
      *   A file extension.
      * @param class-string<MimeMapInterface>|null $mapClass
      *   (Optional) The FQCN of the map class to use.
+     *
+     * @api
      */
     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<string>
+     *
+     * @api
      */
     public function getTypes(): array;
 }

src/TypeInterface.php

@@ -6,8 +6,6 @@
 
 /**
  * Interface for Type objects.
- *
- * @api
  */
 interface TypeInterface
 {
@@ -20,71 +18,95 @@ interface TypeInterface
      *   MIME type string to be parsed.
      * @param class-string<MimeMapInterface>|null $mapClass
      *   (Optional) The FQCN of the map class to use.
+     *
+     * @api
      */
     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;
 
     /**
      * Gets the MIME type's media comment.
      *
      * @throws UndefinedException
+     *
+     * @api
      */
     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;
 
     /**
      * Gets the MIME type's subtype comment.
      *
      * @throws UndefinedException
+     *
+     * @api
      */
     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,30 +116,40 @@ public function hasParameters(): bool;
      * @return TypeParameter[]
      *
      * @throws UndefinedException
+     *
+     * @api
      */
     public function getParameters(): array;
 
     /**
      * Checks if the MIME type has a parameter.
      *
      * @throws UndefinedException
+     *
+     * @api
      */
     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,23 +170,31 @@ 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;
 
     /**
      * 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<int,int|string>
+     *
+     * @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,13 +259,17 @@ public function getDescription(bool $includeAcronym = false): string;
      * @throws MappingException on error.
      *
      * @return list<string>
+     *
+     * @api
      */
     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<string>
+     *
+     * @api
      */
     public function getExtensions(): array;
 }