docs

Signed-off-by: Jan Kowalleck <jan.kowalleck@gmail.com>

README.md

@@ -90,6 +90,12 @@ $bom->getComponents()->addItems(
 );
 ```
 
+## API documentation
+
+There is no pre-rendered documentation at the time.  
+Instead, there is a prepared config for [phpDoc3](https://docs.phpdoc.org/guide/getting-started/index.html)
+that you can use to generate the docs for yourself.
+
 ## Conflicts
 
 Due to the fact that this library was split out of [`/src/Core` of cyclonedx-php-composer (346e6200fb2f5086061b15c2ee44f540893ce97d)](https://github.com/CycloneDX/cyclonedx-php-composer/tree/346e6200fb2f5086061b15c2ee44f540893ce97d/src/Core)  

phpdoc.dist.xml

@@ -15,7 +15,13 @@
                 <path>src</path>
             </source>
             <default-package-name>CycloneDX Library</default-package-name>
-            <include-source>false</include-source>
+            <ignore-tags>
+                <ignore-tag>SuppressWarnings</ignore-tag>
+                <ignore-tag>psalm-suppress</ignore-tag>
+            </ignore-tags>
+            <examples>
+                <path>examples</path>
+            </examples>
         </api>
     </version>
 </phpdocumentor>

src/Core/Serialization/BaseSerializer.php

@@ -33,7 +33,12 @@
 abstract class BaseSerializer implements Serializer
 {
     /**
+     * Get a list of all {@see \CycloneDX\Core\Models\BomRef} in {@see \CycloneDX\Core\Models\Bom}.
+     * The list might contain duplicates.
+     *
      * @return BomRef[]
+     *
+     * @psalm-return list<BomRef>
      */
     private function getAllBomRefs(Bom $bom): array
     {
@@ -59,7 +64,7 @@ private function getAllBomRefs(Bom $bom): array
      *
      * @throws Exception
      *
-     * @psalm-return TNormalizedBom
+     * @return TNormalizedBom a version of the Bom that was normalized for serialization
      */
     private function normalize(BOM $bom)
     {
@@ -95,6 +100,7 @@ final public function serialize(Bom $bom, ?bool $prettyPrint = null): string
      * @return TNormalizedBom a version of the Bom that was normalized for serialization
      */
     abstract protected function realNormalize(Bom $bom);
+    // no typehint for return type, as it is not actually `mixed` but a templated type.
 
     /**
      * Serialize a {@see realNormalize() normalized} version of a {@see \CycloneDX\Core\Models\Bom}.
@@ -106,4 +112,5 @@ abstract protected function realNormalize(Bom $bom);
      * @SuppressWarnings(PHPMD.BooleanArgumentFlag)
      */
     abstract protected function realSerialize($normalizedBom, ?bool $prettyPrint): string;
+    // no typehint for `$normalizedBom` parameter, as it is not actually `mixed` but a templated type.
 }

src/Core/Serialization/Serializer.php

@@ -31,7 +31,7 @@ interface Serializer
     /**
      * Serialize a {@see \CycloneDX\Core\Models\Bom} to {@see string}.
      *
-     * @param Bom  $bom         the bom to serialize
+     * @param Bom  $bom         the BOM to serialize
      * @param bool $prettyPrint whether to beatify the resulting string. A `null` value means no preference.
      *
      * @throws Exception