如何确保我的类型和函数文档出现在 Ballerina Central 中？

Question

我使用文档语法记录了我的Ballerina 代码的公共类型和函数：

documentation {
    Wordpress Client object
    E{{}}
    F{{wordpressApiConfig}} - Wordpress connector configurations
    F{{wordpressApiConnector}} - WordpressConnector Connector object
}

public type WordpressApiClient object {
    public WordpressApiConfiguration wordpressApiConfig = {};
    public WordpressApiConnector wordpressApiConnector = new;

    documentation {Wordpress connector endpoint initialization function
        P{{config}} - Wordpress connector configuration
    }
    public function init(WordpressApiConfiguration config);

    documentation {Return the Wordpress connector client
        R{{}} - Wordpress connector client
    }
    public function getCallerActions() returns WordpressApiConnector;

};

但是，一旦我推送了这个文档，它就不会出现在Ballerina Central 的包描述中。我检查了一些确实显示文档的存储库，并观察到它们遵循不同的语法，涉及行 cmets 和 + 符号。

您能否解释一下当前标准是什么文档样式，以及我是否必须运行不同的命令来生成文档以使其正确显示在 Central 中。

Answer 1

您在此处使用的文档语法是旧语法。这是最近更新的，现在 Ballerina 风格的 markdown 文档语法用于文档。更多详情请访问https://ballerina.io/learn/by-example/documentation.html。

因此，您的示例中的文档应更改为 -

# Wordpress Client object
# + wordpressApiConfig - Wordpress connector configurations
# + wordpressApiConnector - WordpressConnector Connector object

public type WordpressApiClient object {
    public WordpressApiConfiguration wordpressApiConfig = {};
    public WordpressApiConnector wordpressApiConnector = new;

    # Wordpress connector endpoint initialization function
    # + config - Wordpress connector configuration
    public function init(WordpressApiConfiguration config);

    # Return the Wordpress connector client
    # + return - Wordpress connector client
    public function getCallerActions() returns WordpressApiConnector;

};

此更改尚未在 Ballerina 稳定版中提供，但将在本周晚些时候发布的 v0.982.0 中提供。 nightly build 也提供此更改。因此，您可以在稳定版本发布之前使用 nightly build。