wurfapi 9.0.0

唯一名称

为了能够引用 API 中的不同实体，我们需要为它们分配一个名称。

我们在这里使用与standardese中描述的类似方法。

这意味着实体的唯一名称是具有所有范围的名称，例如foo::bar::baz。

• 对于函数，唯一名称包含签名（参数类型和成员函数 cv-qualifier 和 ref-qualifier），例如foo::bar::baz::func() 或foo::bar::baz::func(int a , 字符*) 常量。有关详细信息，请参阅cppreference。

• 对于类模板特化，唯一名称包括特化参数。例如：

  // Here the unique-name is just 'foo'
  template<class T>
  class foo {};
  
  // Here the unique name is foo<int>
  template<>
  class foo<int> {};

• 除了类型之外，我们还有已解析文件的条目。对于文件，唯一名称将是项目根目录的相对路径。

• 对于定义，我们将使用定义的名称。举个例子：

  #define PROJECT_VERSION "1.0.0"

  这里唯一名称将是PROJECT_VERSION。

API 字典

内部结构是具有不同 API 实体的字典。实体的 唯一名称是键，实体类型也是 Python 字典的值，例如：

api = {
  'unique-name': { ... },
  'unique-name': { ... },
  ...
}

为了使这一点更具体，请考虑以下代码：

namespace ns1
{
  class shape
  {
    void print(int a) const;
  };

  namespace ns2
  {
    struct box
    {
      void hello();
    };

    void print();
  }
}

解析上述代码将生成以下 API 字典：

api = {
  'ns1': { 'kind': 'namespace', ...},
  'ns1::shape': { 'kind': 'class', ... },
  'ns1::shape::print(int) const': { kind': function' ... },
  'ns1::ns2': { 'kind': 'namespace', ... },
  'ns1::ns2::box': { 'kind': 'struct', ... },
  'ns1::ns2::box::hello()': { kind': function' ... },
  'ns1::ns2::print()': { 'kind': 'function', ...},
  'ns1.hpp': { 'kind': 'file', ...}
}

不同的实体类型公开了有关 API 的不同信息。我们将在下面记录不同的类型。

我们将一些键设置为可选的，其标记方式如下：

api = {
  'unique-name': {
    'some_key': ...
    Optional('an_optional_key'): ...
  },
  ...
}

命名空间种类

表示 C++ 命名空间的 Python 字典：

info = {
  'kind': 'namespace',
  'name': 'unqualified-name',
  'scope': 'unique-name' | None,
  'members: [ 'unique-name', 'unique-name' ],
  'briefdescription': paragraphs,
  'detaileddescription': paragraphs,
  'inline': True | False
}

注意：目前 Doxygen 不支持解析内联命名空间。因此，您需要使用补丁 API 手动将值从False更改为True 。也许在某个时候https://github.com/doxygen/doxygen/issues/6741 它会被支持。

班级| 结构种类

表示 C++ 类或结构的 Python 字典：

info = {
  'kind': 'class' | 'struct',
  'name': 'unqualified-name',
  'location': location,
  'scope': 'unique-name' | None,
  'access': 'public' | 'protected' | 'private',
  Optional('template_parameters'): template_parameters,
  'members: [ 'unique-name', 'unique-name' ],
  'briefdescription': paragraphs,
  'detaileddescription': paragraphs
}

枚举| 枚举类种类

表示 C++ 枚举或枚举类的 Python 字典：

info = {
  'kind': 'enum',
  'name': 'unqualified-name',
  'location': location,
  'scope': 'unique-name' | None,
  'access': 'public' | 'protected' | 'private',
  'values: [
    {
      'name': 'somename',
      'briefdescription': paragraphs,
      'detaileddescription': paragraphs,
      Optional('value'): 'some value'
    }
   ],
  'briefdescription': paragraphs,
  'detaileddescription': paragraphs
}

类型定义| 使用种类

表示 C++ using 或 typedef 语句的 Python 字典：

info = {
  'kind': 'typedef' | 'using',
  'name': 'unqualified-name',
  'location': location,
  'scope': 'unique-name' | None,
  'access': 'public' | 'protected' | 'private',
  'type': type,
  'briefdescription': paragraphs,
  'detaileddescription': paragraphs
}

定义种类

代表 C/C++ 的 Python 字典定义：

info = {
  'kind': 'define',
  'name': 'name',
  'location': location,
  Optional('initializer'): 'some_value',
  Optional('parameters'): [{
      'name': 'somestring',
      Optional('description'): paragraphs
  }],
  'briefdescription': paragraphs,
  'detaileddescription': paragraphs
}

定义的内容将在初始化字段中。如果定义采用记录的参数，这些参数将位于参数键下。

例子：

1. 定义初始化器：

   #define VERSION "1.0.2"

2. 用参数定义初始化器：

   #define min(X, Y)  ((X) < (Y) ? (X) : (Y))

文件种类

表示项目中文件的 Python 字典：

info = {
  'kind': 'file',
  'name': 'somefile.hpp',
  'path': 'relative/path/to/somefile.hpp',
}

功能种类

表示 C++ 函数的 Python 字典：

  info = {
    'kind': 'function',
    'name': 'unqualified-name',
    'location': location,
    'scope': 'unique-name' | None,
    Optional('return'): {
      'type': type,
      'description': paragraphs
    }
    Optional('template_parameters'): template_parameters,
    'is_const': True | False,
    'is_static': True | False,
    'is_virtual': True | False,
    'is_explicit': True | False,
    'is_inline': True | False,
    'is_constructor': True | False,
    'is_destructor': True | False,
    'trailing_return': True | False,
    'access': 'public' | 'protected' | 'private',
    'briefdescription: paragraphs,
    'detaileddescription: paragraphs,
    'parameters': [
      { 'type': type, Optional('name'): 'somename', 'description': paragraphs },
      ...
    ]
}

如果函数是构造函数或析构函数，则返回键是可选的。

可变种类

表示 C++ 变量的 Python 字典：

info = {
  'kind': 'variable',
  'name': 'unqualified-name',
  Optional('value'): 'some value',
  'type': type,
  'location': location,
  'is_static': True | False,
  'is_mutable': True | False,
  'is_volatile': True | False,
  'is_const': True | False,
  'is_constexpr': True | False,
  'scope': 'unique-name' | None,
  'access': 'public' | 'protected' | 'private',
  'briefdescription: paragraphs,
  'detaileddescription: paragraphs,
}

位置项目

表示位置的 Python 字典：

location = {
  Optional('include'): 'some/header.h',
  'path': 'src/project/header.h',
  'line': 10
  }

• 包含将与 Sphinx conf.py中wurfapi字典中指定的 任何include_paths相关。

• 该路径将相对于项目根文件夹。

类型项目

表示 C++ 类型的 Python 列表：

type = [
  {
    'value': 'sometext',
    Optional('link'): link
  }, ...
]

将类型作为项目列表，我们可以创建到嵌套类型的链接，例如说我们有一个std::unique_ptr<impl>并且我们希望将impl设为链接。这可能看起来像：

"type": [
  {
    "value": "std::unique_ptr<"
  },
  {
    "link": {"url": False, "value": "project::impl"},
    "value": "impl"
  },
  {
    "value": ">"
  }
]

类型列表中的任何空格都应从 Doxygen 输出一直保留到类型列表中。首先，简单地输出类型的值就足够了。不应注入空格或其他内容。

链接项目

表示链接的 Python 字典：

link = { 'url': True | False, 'value': 'somestring' }

如果url是True我们有一个基本的外部引用，否则我们有一个指向 API 内部类型的链接。

参数项

表示函数参数的字典：

parameter = {
  'type': type,
  Optional('name'): 'somestring',
  Optional('description'): paragraphs
}

对于参数，名称也包含在类型列表中。原因是某些参数可能非常复杂，名称嵌入在类型中，例如：

void function(int (*(*foo)())[3]);

这是一个函数，它接受一个参数foo，它是指针函数，它返回指向 int 数组 3 的指针 - 不错吧？无论如何，在这种情况下，参数名称嵌入在参数的类型中。因此，我们采取了简单的做法，wurfapi将始终在类型中包含参数名称。

例如，函数void test(int b)的参数字典 可以是：

{
   'type': [{'value': 'int '}, {'value': 'b'}],
   'name': 'b'
}

模板参数项

表示模板参数的 Python 字典列表：

template_parameters = [{
  'type': type,
  'name': 'somestring',
  Optional('default'): type,
  Optional('description'): paragraphs
}]

文字信息

文本信息存储在列表段落中：

paragraphs = [paragraph]

一个段落由一系列段落元素组成：

paragraph = [
      {
        "kind": "text" | "code" | "list" | "bold" | "italic",
        ...
      },
    ]

段落元素可以是“文本”、“代码”或“列表”三种类型之一：

text = {
  'kind': 'text',
  'content': 'hello',
  Optional('link'): link
  }

code = {
  'kind': 'code',
  'content': 'void print();',
  'is_block': true | false
}

list = {
  'kind': 'list',
  'ordered': true | false,
  'items': [paragraphs] # Each item is a list of paragraphs
}

函数的唯一名称问题

问题等效的 C++ 函数签名可以用多种不同的方式编写：

void hello(const int *x); // x is a pointer to const int
void hello(int const *x); // x is a pointer to const int

我们还可以将星号 ( * ) 向左移动：

void hello(const int* x); // x is a pointer to const int
void hello(int const* x); // x is a pointer to const int

因此，在将函数签名转换为unique-name时，我们需要一些方法来规范化函数签名。我们不能简单地依赖刺痛比较。

根据大量的谷歌搜索，很难为此编写正则表达式。相反，我们将尝试使用解析器：

• Python 解析器：https ://github.com/erezsh/lark

• C++ 语法：http ://www.externsoft.ch/media/swf/cpp11-iso.html#parameters_and_qualifiers

我们只需要解析表示为 http://www.externsoft.ch/media/swf/cpp11-iso.html#parameters_and_qualifiers的函数参数列表。