Improve JSDoc generation (#38)

* Improve maps in JSDoc
* Support optional values in JSDoc

Author: vearutop

CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.31] - 2021-04-12
+
+### Added
+- Support for optional values in JSDoc.
+
+### Fixed
+- Map types in JSDoc.
+
 ## [0.2.30] - 2021-04-08
 
 ### Added
@@ -74,6 +82,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 - Description trimming bug.
 
+[0.2.31]: https://github.com/swaggest/php-code-builder/compare/v0.2.30...v0.2.31
 [0.2.30]: https://github.com/swaggest/php-code-builder/compare/v0.2.29...v0.2.30
 [0.2.29]: https://github.com/swaggest/php-code-builder/compare/v0.2.28...v0.2.29
 [0.2.28]: https://github.com/swaggest/php-code-builder/compare/v0.2.27...v0.2.28

src/JSDoc/TypeBuilder.php

@@ -153,7 +153,7 @@ public function getTypeString($schema, $path = '')
 
             if ($schema->additionalProperties instanceof Schema) {
                 $typeName = $this->getTypeString($schema->additionalProperties, $path . '/additionalProperties');
-                $or [] = "object<string, $typeName>";
+                $or [] = "Object.<String,$typeName>";
                 $typeAdded = true;
             }
 
@@ -168,7 +168,7 @@ public function getTypeString($schema, $path = '')
             }
 
             if (!$typeAdded) {
-                $or [] = 'object';
+                $or [] = 'Object';
             }
         }
 
@@ -177,37 +177,37 @@ public function getTypeString($schema, $path = '')
 
             if ($schema->items instanceof Schema) {
                 $typeName = $this->getTypeString($schema->items, $path . '/items');
-                $or [] = "array<$typeName>";
+                $or [] = "Array<$typeName>";
                 $typeAdded = true;
             }
 
             if ($schema->additionalItems instanceof Schema) {
                 $typeName = $this->getTypeString($schema->additionalItems, $path . '/additionalItems');
-                $or [] = "array<$typeName>";
+                $or [] = "Array<$typeName>";
                 $typeAdded = true;
             }
 
             if (!$typeAdded) {
-                $or [] = 'array';
+                $or [] = 'Array';
             }
         }
 
         if ($isString) {
-            $or [] = 'string';
+            $or [] = 'String';
         }
 
         if ($isNumber) {
-            $or [] = 'number';
+            $or [] = 'Number';
         }
 
         if ($isBoolean) {
-            $or [] = 'boolean';
+            $or [] = 'Boolean';
         }
 
         $res = '';
         foreach ($or as $item) {
             if (!empty($item) && $item !== '*') {
-                $res .= '|' . $item;
+                $res .= '|' . ($isOptional ? '?' : '') . $item;
             }
         }
 
@@ -256,14 +256,14 @@ private function makeObjectTypeDef(Schema $schema, $path)
         $res = <<<JSDOC
 /**$head
  * @typedef {$typeName}
- * @type {object}
+ * @type {Object}
 
 JSDOC;
         if (!empty($schema->properties)) {
             foreach ($schema->properties as $propertyName => $propertySchema) {
                 $typeString = $this->getTypeString($propertySchema, $path . '/' . $propertyName);
                 $res .= <<<JSDOC
- * @property {{$typeString}} {$propertyName}{$this->description($propertySchema)}.
+ * @property {{$typeString}} {$propertyName}{$this->description($propertySchema)}
 
 JSDOC;
 
@@ -285,7 +285,7 @@ private function description(Schema $schema)
     {
         $res = str_replace("\n", " ", $schema->title . $schema->description);
         if ($res) {
-            return ' - ' . rtrim($res, '.');
+            return ' - ' . rtrim($res, '.') . '.';
         }
 
         return '';

tests/src/PHPUnit/JSDoc/JSDocTest.php

@@ -36,12 +36,12 @@ public function testJsonSchema()
         $this->assertSame(<<<'JS'
 /**
  * @typedef Person
- * @type {object}
- * @property {string} name - Person name.
- * @property {number} age.
- * @property {boolean} isMale.
- * @property {Person} partner.
- * @property {array<Person>} children.
+ * @type {Object}
+ * @property {String} name - Person name.
+ * @property {Number} age
+ * @property {Boolean} isMale
+ * @property {Person} partner
+ * @property {Array<Person>} children
  */