tdlight-team/tdlight
tdlight-team
/
tdlight
1
1
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Better documentation for type constructors. 

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)
@ -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) {

15
td/generate/DoxygenTlDocumentationGenerator.php
View File

@ -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;

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)
@ -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;

21
td/generate/TlDocumentationGenerator.php
View File

@ -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 = '';