Better documentation for type constructors.

GitOrigin-RevId: e41a742ced36e42205190572501c4f02b075bbba

td/generate/DotnetTlDocumentationGenerator.php

@@ -158,9 +158,10 @@ EOT
 );
     }
 
-    protected function getFunctionReturnTypeDescription($return_type)
+    protected function getFunctionReturnTypeDescription($return_type, $for_constructor)
     {
-        return "\r\n/// <para>Returns <see cref=\"".substr($return_type, 0, -1).'"/>.</para>';
+        $shift = $for_constructor ? '  ' : '';
+        return "\r\n$shift/// <para>Returns <see cref=\"".substr($return_type, 0, -1).'"/>.</para>';
     }
 
     protected function addClassDocumentation($class_name, $base_class_name, $description)
@@ -189,17 +190,17 @@ EOT
 );
     }
 
-    protected function addDefaultConstructorDocumentation($class_name)
+    protected function addDefaultConstructorDocumentation($class_name, $class_description)
     {
         $this->addDocumentation("  $class_name();", <<<EOT
   /// <summary>
-  /// Default constructor.
+  /// $class_description
   /// </summary>
 EOT
 );
     }
 
-    protected function addFullConstructorDocumentation($class_name, $known_fields, $info)
+    protected function addFullConstructorDocumentation($class_name, $class_description, $known_fields, $info)
     {
         $full_constructor = "  $class_name(";
         $colon = '';
@@ -216,7 +217,7 @@ EOT
 
         $full_doc = <<<EOT
   /// <summary>
-  /// Constructor for initialization of all fields.
+  /// $class_description
   /// </summary>
 EOT;
         foreach ($known_fields as $name => $type) {

td/generate/DoxygenTlDocumentationGenerator.php

@@ -196,7 +196,7 @@ EOT
         $this->addDocumentation('object_ptr<ToType> move_object_as(FromType &&from) {', <<<EOT
 /**
  * A function to cast a wrapped in td::td_api::object_ptr TDLib API object to its subclass or superclass.
- * Casting an object to an incorrect type will lead to undefined bejaviour.
+ * Casting an object to an incorrect type will lead to undefined behaviour.
  * Usage example:
  * \\code
  * td::td_api::object_ptr<td::td_api::callState> call_state = ...;
@@ -321,9 +321,10 @@ EOT
 );
     }
 
-    protected function getFunctionReturnTypeDescription($return_type)
+    protected function getFunctionReturnTypeDescription($return_type, $for_constructor)
     {
-        return PHP_EOL.' *'.PHP_EOL." * Returns $return_type.";
+        $shift = $for_constructor ? '   ' : ' ';
+        return PHP_EOL.$shift.'*'.PHP_EOL.$shift."* Returns $return_type.";
     }
 
     protected function addClassDocumentation($class_name, $base_class_name, $description)
@@ -344,17 +345,17 @@ EOT
 );
     }
 
-    protected function addDefaultConstructorDocumentation($class_name)
+    protected function addDefaultConstructorDocumentation($class_name, $class_description)
     {
         $this->addDocumentation("  $class_name();", <<<EOT
   /**
-   * Default constructor. All fields will be value-initilaized.
+   * $class_description
    */
 EOT
 );
     }
 
-    protected function addFullConstructorDocumentation($class_name, $known_fields, $info)
+    protected function addFullConstructorDocumentation($class_name, $class_description, $known_fields, $info)
     {
         $explicit = count($known_fields) === 1 ? 'explicit ' : '';
         $full_constructor = "  $explicit$class_name(";
@@ -367,7 +368,7 @@ EOT
 
         $full_doc = <<<EOT
   /**
-   * Constructor for initialization of all fields.
+   * $class_description
    *
 
 EOT;

td/generate/JavadocTlDocumentationGenerator.php

@@ -190,9 +190,10 @@ EOT
 );
     }
 
-    protected function getFunctionReturnTypeDescription($return_type)
+    protected function getFunctionReturnTypeDescription($return_type, $for_constructor)
     {
-        return PHP_EOL.'     *'.PHP_EOL."     * <p> Returns {@link $return_type $return_type} </p>";
+        $shift = $for_constructor ? '         ' : '     ';
+        return PHP_EOL.$shift.'*'.PHP_EOL.$shift."* <p> Returns {@link $return_type $return_type} </p>";
     }
 
     protected function addClassDocumentation($class_name, $base_class_name, $description)
@@ -219,17 +220,17 @@ EOT
         }
     }
 
-    protected function addDefaultConstructorDocumentation($class_name)
+    protected function addDefaultConstructorDocumentation($class_name, $class_description)
     {
         $this->addDocumentation("        public $class_name() {", <<<EOT
         /**
-         * Default constructor.
+         * $class_description
          */
 EOT
 );
     }
 
-    protected function addFullConstructorDocumentation($class_name, $known_fields, $info)
+    protected function addFullConstructorDocumentation($class_name, $class_description, $known_fields, $info)
     {
         $full_constructor = "        public $class_name(";
         $colon = '';
@@ -241,7 +242,7 @@ EOT
 
         $full_doc = <<<EOT
         /**
-         * Constructor for initialization of all fields.
+         * $class_description
          *
 
 EOT;

td/generate/TlDocumentationGenerator.php

@@ -87,15 +87,15 @@ abstract class TlDocumentationGenerator
 
     abstract protected function addAbstractClassDocumentation($class_name, $value);
 
-    abstract protected function getFunctionReturnTypeDescription($return_type);
+    abstract protected function getFunctionReturnTypeDescription($return_type, $for_constructor);
 
     abstract protected function addClassDocumentation($class_name, $base_class_name, $description);
 
     abstract protected function addFieldDocumentation($class_name, $field_name, $type_name, $field_info, $may_be_null);
 
-    abstract protected function addDefaultConstructorDocumentation($class_name);
+    abstract protected function addDefaultConstructorDocumentation($class_name, $class_description);
 
-    abstract protected function addFullConstructorDocumentation($class_name, $known_fields, $info);
+    abstract protected function addFullConstructorDocumentation($class_name, $class_description, $known_fields, $info);
 
     public function generate($tl_scheme_file, $source_file)
     {
@@ -237,7 +237,7 @@ abstract class TlDocumentationGenerator
                 $base_class_name = $current_class ?: $this->getBaseClassName($is_function);
                 $class_description = $info['description'];
                 if ($is_function) {
-                    $class_description .= $this->getFunctionReturnTypeDescription($this->getTypeName($type));
+                    $class_description .= $this->getFunctionReturnTypeDescription($this->getTypeName($type), false);
                 }
                 $this->addClassDocumentation($class_name, $base_class_name, $class_description);
 
@@ -246,10 +246,19 @@ abstract class TlDocumentationGenerator
                     $this->addFieldDocumentation($class_name, $this->getFieldName($name, $class_name), $this->getTypeName($type), $info[$name], $may_be_null);
                 }
 
-                $this->addDefaultConstructorDocumentation($class_name);
+                if ($is_function) {
+                    $default_constructor_prefix = 'Default constructor for a function, which ';
+                    $full_constructor_prefix = 'Creates a function, which ';
+                    $class_description = lcfirst($info['description']);
+                    $class_description .= $this->getFunctionReturnTypeDescription($this->getTypeName($type), true);
+                } else {
+                    $default_constructor_prefix = '';
+                    $full_constructor_prefix = '';
+                }
+                $this->addDefaultConstructorDocumentation($class_name, $default_constructor_prefix.$class_description);
 
                 if ($known_fields) {
-                    $this->addFullConstructorDocumentation($class_name, $known_fields, $info);
+                    $this->addFullConstructorDocumentation($class_name, $full_constructor_prefix.$class_description, $known_fields, $info);
                 }
 
                 $description = '';