andreacavalli/tdlib-fork
Archived
1
0
Fork 0
Code Pull Requests Releases Activity

Better documentation for type constructors.

Browse Source 
GitOrigin-RevId: e41a742ced36e42205190572501c4f02b075bbba
This commit is contained in:
levlam 2019-03-25 02:07:31 +03:00
parent c2991967ca
commit 1c78b6994a
4 changed files with 37 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
td/generate/DotnetTlDocumentationGenerator.php
View File

@ -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) 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 $this->addDocumentation(" $class_name();", <<<EOT
/// <summary> /// <summary>
/// Default constructor. /// $class_description
/// </summary> /// </summary>
EOT EOT
); );
} }
protected function addFullConstructorDocumentation($class_name, $known_fields, $info) protected function addFullConstructorDocumentation($class_name, $class_description, $known_fields, $info)
{ {
$full_constructor = " $class_name("; $full_constructor = " $class_name(";
$colon = ''; $colon = '';
@ -216,7 +217,7 @@ EOT
$full_doc = <<<EOT $full_doc = <<<EOT
/// <summary> /// <summary>
/// Constructor for initialization of all fields. /// $class_description
/// </summary> /// </summary>
EOT; EOT;
foreach ($known_fields as $name => $type) { foreach ($known_fields as $name => $type) {

15
td/generate/DoxygenTlDocumentationGenerator.php
View File

@ -196,7 +196,7 @@ EOT
$this->addDocumentation('object_ptr<ToType> move_object_as(FromType &&from) {', <<<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. * 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: * Usage example:
* \\code * \\code
* td::td_api::object_ptr<td::td_api::callState> call_state = ...; * 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) 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 $this->addDocumentation(" $class_name();", <<<EOT
/** /**
* Default constructor. All fields will be value-initilaized. * $class_description
*/ */
EOT 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 ' : ''; $explicit = count($known_fields) === 1 ? 'explicit ' : '';
$full_constructor = " $explicit$class_name("; $full_constructor = " $explicit$class_name(";
@ -367,7 +368,7 @@ EOT
$full_doc = <<<EOT $full_doc = <<<EOT
/** /**
* Constructor for initialization of all fields. * $class_description
* *
EOT; EOT;

13
td/generate/JavadocTlDocumentationGenerator.php
View File

@ -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) 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 $this->addDocumentation(" public $class_name() {", <<<EOT
/** /**
* Default constructor. * $class_description
*/ */
EOT EOT
); );
} }
protected function addFullConstructorDocumentation($class_name, $known_fields, $info) protected function addFullConstructorDocumentation($class_name, $class_description, $known_fields, $info)
{ {
$full_constructor = " public $class_name("; $full_constructor = " public $class_name(";
$colon = ''; $colon = '';
@ -241,7 +242,7 @@ EOT
$full_doc = <<<EOT $full_doc = <<<EOT
/** /**
* Constructor for initialization of all fields. * $class_description
* *
EOT; EOT;

21
td/generate/TlDocumentationGenerator.php
View File

@ -87,15 +87,15 @@ abstract class TlDocumentationGenerator
abstract protected function addAbstractClassDocumentation($class_name, $value); 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 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 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) public function generate($tl_scheme_file, $source_file)
{ {
@ -237,7 +237,7 @@ abstract class TlDocumentationGenerator
$base_class_name = $current_class ?: $this->getBaseClassName($is_function); $base_class_name = $current_class ?: $this->getBaseClassName($is_function);
$class_description = $info['description']; $class_description = $info['description'];
if ($is_function) { 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); $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->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) { if ($known_fields) {
$this->addFullConstructorDocumentation($class_name, $known_fields, $info); $this->addFullConstructorDocumentation($class_name, $full_constructor_prefix.$class_description, $known_fields, $info);
} }
$description = ''; $description = '';