Skip to content

Commit

Permalink
feat: add sdk doc
Browse files Browse the repository at this point in the history
  • Loading branch information
@yndu13
飞澋 authored and yndu13 committed Jul 18, 2024
1 parent e6b14b6 commit ae46f57
Show file tree
Hide file tree
Showing 14 changed files with 236 additions and 52 deletions.
100 changes: 67 additions & 33 deletions lib/generator.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -437,20 +437,9 @@ ${this.config.clientName}::main(array_slice($argv, 1));`);
var summary = ast.items.find((item) => {
return item.type === 'summary';
});
var _return = ast.items.find((item) => {
return item.type === 'return';
});
var deprecated = ast.items.find((item) => {
return item.type === 'deprecated';
});
var params = ast.items.filter((item) => {
return item.type === 'param';
}).map((item) => {
return {
name: item.name.id,
text: item.text.text.trimEnd()
};
});
var throws = ast.items.filter((item) => {
return item.type === 'throws';
}).map((item) => {
Expand All @@ -459,7 +448,6 @@ ${this.config.clientName}::main(array_slice($argv, 1));`);

var descriptionText = description ? description.text.text.trimEnd() : '';
var summaryText = summary ? summary.text.text.trimEnd() : '';
var returnText = _return ? _return.text.text.trimEnd() : '';
let hasNextSection = false;

this.emit('/**\n', level);
Expand All @@ -473,7 +461,6 @@ ${this.config.clientName}::main(array_slice($argv, 1));`);
if (hasNextSection) {
this.emit(' * \n', level);
}
this.emit(' * @remarks\n', level);
descriptionText.split('\n').forEach((line) => {
this.emit(` * ${line}\n`, level);
});
Expand All @@ -483,28 +470,29 @@ ${this.config.clientName}::main(array_slice($argv, 1));`);
if (hasNextSection) {
this.emit(' * \n', level);
}
if (deprecated.text.text.trimEnd() === '') {
this.emit(' * @deprecated\n', level);
} else {
this.emit(` * @deprecated ${deprecated.text.text.trimEnd()}\n`, level);
}
hasNextSection = true;
}
if (params.length > 0) {
if (hasNextSection) {
this.emit(' * \n', level);
}
params.forEach((item) => {
this.emit(` * @param ${item.name} - ${item.text}\n`, level);
const deprecatedText = deprecated.text.text.trimEnd();
this.emit(' * @deprecated ', level);
deprecatedText.split('\n').forEach((line, index) => {
if (index === 0) {
this.emit(`${line}\n`);
} else {
this.emit(` * ${line}\n`, level);
}
});
}
if (returnText !== '') {
this.emit(` * @returns ${returnText}\n`, level);
hasNextSection = true;
}
if (throws.length > 0) {
this.emit(' * \n', level);
throws.forEach((item) => {
this.emit(` * @throws ${item}\n`, level);
this.emit(' * @throws ', level);
const items = item.trimEnd().split('\n');
items.forEach((line, index) => {
if (index === 0) {
this.emit(`${line}\n`);
} else {
this.emit(` * ${line}\n`, level);
}
});
});
}
if(bottom) {
Expand Down Expand Up @@ -898,7 +886,7 @@ ${this.config.clientName}::main(array_slice($argv, 1));`);
this.emit(realModelName);
} else if (value.tag === Tag.ID && value.idType === 'module') {
let moduleName = _name(value);
if(this.builtin[moduleName]) {
if (this.builtin[moduleName]) {
moduleName = this.getType(moduleName);
} else {
moduleName = this.getRealClientName(moduleName);
Expand Down Expand Up @@ -1061,12 +1049,58 @@ ${this.config.clientName}::main(array_slice($argv, 1));`);
assert.equal(ast.type, 'modelBody');
let node;
for (let i = 0; i < ast.nodes.length; i++) {
node = ast.nodes[i];
// TODO document gen
node = ast.nodes[i];
let comments = DSL.comment.getFrontComments(this.comments, node.tokenRange[0]);
this.visitComments(comments, level);
const description = this.getAttributes(node, 'description');
const example = this.getAttributes(node, 'example');
const checkBlank = this.getAttributes(node, 'checkBlank');
const nullable = this.getAttributes(node, 'nullable');
const sensitive = this.getAttributes(node, 'sensitive');
const deprecated = this.getAttributes(node, 'deprecated');
let hasNextSection = false;
this.emit('/**\n', level);
if (description) {
const descriptions = description.trimEnd().split('\n');
for (let j = 0; j < descriptions.length; j++) {
this.emit(` * ${descriptions[j]}\n`, level);
}
hasNextSection = true;
}
if (example) {
if (hasNextSection) {
this.emit(' * \n', level);
}
const examples = example.trimEnd().split('\n');
this.emit(' * **example:**\n', level);
for (let j = 0; j < examples.length; j++) {
this.emit(` * ${examples[j]}\n`, level);
}
hasNextSection = true;
}
if (typeof checkBlank !== 'undefined') {
if (hasNextSection) {
this.emit(' * \n', level);
}
this.emit(` * **check if is blank:** ${checkBlank}\n`, level);
hasNextSection = true;
}
if (typeof nullable !== 'undefined') {
if (hasNextSection) {
this.emit(' * \n', level);
}
this.emit(` * **if can be null:** ${nullable}\n`, level);
hasNextSection = true;
}
if (typeof sensitive !== 'undefined') {
if (hasNextSection) {
this.emit(' * \n', level);
}
this.emit(` * **if sensitive:** ${sensitive}\n`, level);
}
if (deprecated === 'true') {
this.emit(' * @deprecated\n', level);
}
this.emit(' * @var ', level);
this.visitFieldType(node.fieldValue, level, _name(node.fieldName));
this.emit('\n');
Expand Down
68 changes: 64 additions & 4 deletions tests/expected/annotation/Client.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,6 @@
use AlibabaCloud\Dara\Exception\DaraException;
use AlibabaCloud\Dara\Exception\DaraUnableRetryException;
/**
* @remarks
* top annotation
*/
class Client {
Expand All @@ -20,15 +19,13 @@ class Client {


/**
* @remarks
* Init Func
*/
public function __construct()
{
}

/**
* @remarks
* testAPI
* @return void
*/
Expand Down Expand Up @@ -73,12 +70,75 @@ public function testAPI()
}

/**
* @remarks
* testFunc
* @return void
*/
static public function testFunc()
{
}

// Deprecated
/**
* Queries available Alibaba Cloud regions. The natural language that is used to filter responses. For more information, visit [RFC 7231](https://tools.ietf.org/html/rfc7231). Valid values:
* * zh-CN: Chinese
* * en-US: English
* * ja: Japanese
*
* Queries available Alibaba Cloud regions. The natural language that is used to filter responses. For more information, visit [RFC 7231](https://tools.ietf.org/html/rfc7231). Valid values:
* * zh-CN: Chinese
* * en-US: English
* * ja: Japanese
*
* Default value: zh-CN.
*
*
* > 这是Note的内容
*
* > Notice: 这是注意的内容
*
* @deprecated deprecatedFunc is deprecated.
*
* @throws InternalError Server error. 500 服务器端出现未知异常。
* @throws StackNotFound The Stack (%(stack_name)s) could not be found. 404 资源栈不存在。
* @param string $test
* @param string $_test
* @return void
*/
static public function deprecatedFunc($test, $_test)
{
// empty comment1
// empty comment2
}

/**
* annotation test summary
* summary description1
* summary description2
*
* @deprecated test is deprecated, use xxx instead.
* deprecated description1
* deprecated description2
*
* @throws InternalError Server error. 500 服务器端出现未知异常。
* @param string $test
* @param string $_test
* @return void
*/
static public function multiLineAnnotation($test, $_test)
{
}

/**
* @deprecated deprecated test for line break.
*
* @throws InternalError Server error. 500 服务器端出现未知异常。
* throws test for line break.
* @param string $test
* @param string $_test
* @return void
*/
static public function lineBreakAnnotation($test, $_test)
{
}

}
2 changes: 1 addition & 1 deletion tests/expected/annotation/Models/Test.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,11 @@
namespace Dara\PHP\Tests\Models;
use AlibabaCloud\Dara\Model;
/**
* @remarks
* TestModel
*/
class Test extends Model {
/**
* Alichange app id
* @var string
*/
public $test;
Expand Down
8 changes: 0 additions & 8 deletions tests/expected/comment/Client.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,6 @@
use Dara\PHP\Tests\Models\Test3;
// top comment
/**
* @remarks
* top annotation
*/
class Client {
Expand All @@ -24,7 +23,6 @@ class Client {


/**
* @remarks
* Init Func
*/
// comment between init and annotation
Expand All @@ -51,7 +49,6 @@ public function __construct()
//testAPI comment one
//testAPI comment two
/**
* @remarks
* testAPI
* @return void
*/
Expand Down Expand Up @@ -189,12 +186,7 @@ static public function staticFunc()
}

/**
* @remarks
* testFunc
*
* @param str - description: string parameter
* @param val - description: boolean parameter
* @returns description for return
* @param string $str
* @param boolean $val
* @return void
Expand Down
16 changes: 15 additions & 1 deletion tests/expected/comment/Models/Test1.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,16 +6,30 @@
use AlibabaCloud\Dara\Model;
// import comment
/**
* @remarks
* TestModel
*/
class Test1 extends Model {
/**
* test desc
*
* **check if is blank:** false
*
* **if can be null:** false
*
* **if sensitive:** false
* @var string
*/
public $test;
//model的test back comment
/**
* test2 desc
*
* **check if is blank:** true
*
* **if can be null:** true
*
* **if sensitive:** true
* @deprecated
* @var string
*/
public $test2;
Expand Down
3 changes: 2 additions & 1 deletion tests/expected/comment/Models/Test2.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,17 +5,18 @@
namespace Dara\PHP\Tests\Models;
use AlibabaCloud\Dara\Model;
/**
* @remarks
* TestModel2
*/
class Test2 extends Model {
// model的test front comment
/**
* test desc
* @var string
*/
public $test;
// model的test2 front comment
/**
* test2 desc
* @var string
*/
public $test2;
Expand Down
3 changes: 2 additions & 1 deletion tests/expected/comment/Models/Test3.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,18 +5,19 @@
namespace Dara\PHP\Tests\Models;
use AlibabaCloud\Dara\Model;
/**
* @remarks
* TestModel3
*/
class Test3 extends Model {
// model的test front comment
/**
* test desc
* @var string
*/
public $test;
// empty comment1
// empy comment2
/**
* test desc
* @var string
*/
public $test1;
Expand Down
Loading

0 comments on commit ae46f57

Please sign in to comment.