mirror of
https://github.com/fmtlib/fmt.git
synced 2024-10-06 15:00:19 +00:00
Add macro support to api doc extraction
This commit is contained in:
parent
dd3b3f937b
commit
0714113974
24
doc/api.md
24
doc/api.md
@ -275,7 +275,7 @@ Unused arguments are allowed as in Python's `str.format` and ordinary functions.
|
|||||||
|
|
||||||
Named arguments are not supported in compile-time checks at the moment.
|
Named arguments are not supported in compile-time checks at the moment.
|
||||||
|
|
||||||
### Argument Lists
|
### Type Erasure
|
||||||
|
|
||||||
You can create your own formatting function with compile-time checks and
|
You can create your own formatting function with compile-time checks and
|
||||||
small binary footprint, for example ([run](https://godbolt.org/z/b9Pbasvzc)):
|
small binary footprint, for example ([run](https://godbolt.org/z/b9Pbasvzc)):
|
||||||
@ -493,7 +493,8 @@ chrono-format-specifications).
|
|||||||
|
|
||||||
::: gmtime(std::time_t)
|
::: gmtime(std::time_t)
|
||||||
|
|
||||||
## Standard Library Types Formatting {#std-api}
|
<a id="std-api"></a>
|
||||||
|
## Standard Library Types Formatting
|
||||||
|
|
||||||
`fmt/std.h` provides formatters for:
|
`fmt/std.h` provides formatters for:
|
||||||
|
|
||||||
@ -550,13 +551,12 @@ Format string compilation can generate more binary code compared to the
|
|||||||
default API and is only recommended in places where formatting is a
|
default API and is only recommended in places where formatting is a
|
||||||
performance bottleneck.
|
performance bottleneck.
|
||||||
|
|
||||||
:: {.doxygendefine}
|
::: FMT_COMPILE
|
||||||
FMT_COMPILE
|
|
||||||
::
|
|
||||||
|
|
||||||
::: operator""_cf
|
::: operator""_cf
|
||||||
|
|
||||||
## Terminal Color and Text Style {#color-api}
|
<a id="color-api"></a>
|
||||||
|
## Terminal Color and Text Style
|
||||||
|
|
||||||
`fmt/color.h` provides support for terminal color and text style output.
|
`fmt/color.h` provides support for terminal color and text style output.
|
||||||
|
|
||||||
@ -568,13 +568,15 @@ FMT_COMPILE
|
|||||||
|
|
||||||
::: styled(const T&, text_style)
|
::: styled(const T&, text_style)
|
||||||
|
|
||||||
## System APIs {#os-api}
|
<a id="os-api"></a>
|
||||||
|
## System APIs
|
||||||
|
|
||||||
::: ostream
|
::: ostream
|
||||||
|
|
||||||
::: windows_error
|
::: windows_error
|
||||||
|
|
||||||
## `std::ostream` Support {#ostream-api}
|
<a id="ostream-api"></a>
|
||||||
|
## `std::ostream` Support
|
||||||
|
|
||||||
`fmt/ostream.h` provides `std::ostream` support including formatting of
|
`fmt/ostream.h` provides `std::ostream` support including formatting of
|
||||||
user-defined types that have an overloaded insertion operator
|
user-defined types that have an overloaded insertion operator
|
||||||
@ -601,14 +603,16 @@ you should provide a `formatter` specialization inherited from
|
|||||||
|
|
||||||
::: print(std::ostream&, format_string<T...>, T&&...)
|
::: print(std::ostream&, format_string<T...>, T&&...)
|
||||||
|
|
||||||
## Dynamic Argument Lists {#args-api}
|
<a id="args-api"></a>
|
||||||
|
## Dynamic Argument Lists
|
||||||
|
|
||||||
The header `fmt/args.h` provides `dynamic_format_arg_store`, a builder-like API
|
The header `fmt/args.h` provides `dynamic_format_arg_store`, a builder-like API
|
||||||
that can be used to construct format argument lists dynamically.
|
that can be used to construct format argument lists dynamically.
|
||||||
|
|
||||||
::: dynamic_format_arg_store
|
::: dynamic_format_arg_store
|
||||||
|
|
||||||
## `printf` Formatting {#printf-api}
|
<a id="printf-api"></a>
|
||||||
|
## `printf` Formatting
|
||||||
|
|
||||||
The header `fmt/printf.h` provides `printf`-like formatting
|
The header `fmt/printf.h` provides `printf`-like formatting
|
||||||
functionality. The following functions use [printf format string
|
functionality. The following functions use [printf format string
|
||||||
|
@ -30,17 +30,15 @@ template <typename S>
|
|||||||
struct is_compiled_string : std::is_base_of<compiled_string, S> {};
|
struct is_compiled_string : std::is_base_of<compiled_string, S> {};
|
||||||
|
|
||||||
/**
|
/**
|
||||||
\rst
|
* Converts a string literal `s` into a format string that will be parsed at
|
||||||
Converts a string literal *s* into a format string that will be parsed at
|
* compile time and converted into efficient formatting code. Requires C++17
|
||||||
compile time and converted into efficient formatting code. Requires C++17
|
* `constexpr if` compiler support.
|
||||||
``constexpr if`` compiler support.
|
*
|
||||||
|
* **Example**::
|
||||||
**Example**::
|
*
|
||||||
|
* // Converts 42 into std::string using the most efficient method and no
|
||||||
// Converts 42 into std::string using the most efficient method and no
|
* // runtime format string processing.
|
||||||
// runtime format string processing.
|
* std::string s = fmt::format(FMT_COMPILE("{}"), 42);
|
||||||
std::string s = fmt::format(FMT_COMPILE("{}"), 42);
|
|
||||||
\endrst
|
|
||||||
*/
|
*/
|
||||||
#if defined(__cpp_if_constexpr) && defined(__cpp_return_type_deduction)
|
#if defined(__cpp_if_constexpr) && defined(__cpp_return_type_deduction)
|
||||||
# define FMT_COMPILE(s) \
|
# define FMT_COMPILE(s) \
|
||||||
|
@ -73,6 +73,8 @@ def normalize_type(type: str) -> str:
|
|||||||
return type.replace(' &', '&').replace(' *', '*')
|
return type.replace(' &', '&').replace(' *', '*')
|
||||||
|
|
||||||
def convert_type(type: et.Element) -> str:
|
def convert_type(type: et.Element) -> str:
|
||||||
|
if type is None:
|
||||||
|
return None
|
||||||
result = type.text if type.text else ''
|
result = type.text if type.text else ''
|
||||||
for ref in type:
|
for ref in type:
|
||||||
result += ref.text
|
result += ref.text
|
||||||
@ -98,20 +100,27 @@ def convert_return_type(d: Definition, node: et.Element) -> None:
|
|||||||
|
|
||||||
def render_decl(d: Definition) -> None:
|
def render_decl(d: Definition) -> None:
|
||||||
text = '<pre><code class="language-cpp">'
|
text = '<pre><code class="language-cpp">'
|
||||||
|
|
||||||
if d.template_params is not None:
|
if d.template_params is not None:
|
||||||
text += 'template <'
|
text += 'template <'
|
||||||
text += ', '.join(
|
text += ', '.join(
|
||||||
[f'{p.type} {p.name}'.rstrip() for p in d.template_params])
|
[f'{p.type} {p.name}'.rstrip() for p in d.template_params])
|
||||||
text += '>\n'
|
text += '>\n'
|
||||||
|
|
||||||
|
end = ';'
|
||||||
if d.kind == 'function' or d.kind == 'variable':
|
if d.kind == 'function' or d.kind == 'variable':
|
||||||
text += d.type
|
text += d.type + ' '
|
||||||
elif d.kind == 'typedef':
|
elif d.kind == 'typedef':
|
||||||
text += 'using'
|
text += 'using '
|
||||||
|
elif d.kind == 'define':
|
||||||
|
end = ''
|
||||||
else:
|
else:
|
||||||
text += d.kind
|
text += d.kind + ' '
|
||||||
text += ' ' + d.name
|
text += d.name
|
||||||
|
|
||||||
if d.params is not None:
|
if d.params is not None:
|
||||||
params = ', '.join([f'{p.type} {p.name}' for p in d.params])
|
params = ', '.join([
|
||||||
|
(p.type + ' ' if p.type else '') + p.name for p in d.params])
|
||||||
text += '(' + escape_html(params) + ')'
|
text += '(' + escape_html(params) + ')'
|
||||||
if d.trailing_return_type:
|
if d.trailing_return_type:
|
||||||
text += '\n ' \
|
text += '\n ' \
|
||||||
@ -119,7 +128,8 @@ def render_decl(d: Definition) -> None:
|
|||||||
text += ' -> ' + escape_html(d.trailing_return_type)
|
text += ' -> ' + escape_html(d.trailing_return_type)
|
||||||
elif d.kind == 'typedef':
|
elif d.kind == 'typedef':
|
||||||
text += ' = ' + escape_html(d.type)
|
text += ' = ' + escape_html(d.type)
|
||||||
text += ';'
|
|
||||||
|
text += end
|
||||||
text += '</code></pre>\n'
|
text += '</code></pre>\n'
|
||||||
return text
|
return text
|
||||||
|
|
||||||
@ -174,50 +184,12 @@ class CxxHandler(BaseHandler):
|
|||||||
if p.returncode != 0:
|
if p.returncode != 0:
|
||||||
raise CalledProcessError(p.returncode, cmd)
|
raise CalledProcessError(p.returncode, cmd)
|
||||||
|
|
||||||
def collect(self, identifier: str, config: Mapping[str, Any]) -> Definition:
|
with open(os.path.join(self._doxyxml_dir, 'compile_8h.xml')) as f:
|
||||||
qual_name = 'fmt::' + identifier
|
self._file_doxyxml = et.parse(f)
|
||||||
|
|
||||||
param_str = None
|
def collect_compound(self, identifier: str,
|
||||||
paren = qual_name.find('(')
|
cls: list[et.Element]) -> Definition:
|
||||||
if paren > 0:
|
'''Collect a compound definition such as a struct.'''
|
||||||
qual_name, param_str = qual_name[:paren], qual_name[paren + 1:-1]
|
|
||||||
|
|
||||||
colons = qual_name.rfind('::')
|
|
||||||
namespace, name = qual_name[:colons], qual_name[colons + 2:]
|
|
||||||
|
|
||||||
# Load XML.
|
|
||||||
doxyxml = self._ns2doxyxml.get(namespace)
|
|
||||||
if doxyxml is None:
|
|
||||||
path = f'namespace{namespace.replace("::", "_1_1")}.xml'
|
|
||||||
with open(os.path.join(self._doxyxml_dir, path)) as f:
|
|
||||||
doxyxml = et.parse(f)
|
|
||||||
self._ns2doxyxml[namespace] = doxyxml
|
|
||||||
|
|
||||||
nodes = doxyxml.findall(
|
|
||||||
f"compounddef/sectiondef/memberdef/name[.='{name}']/..")
|
|
||||||
candidates = []
|
|
||||||
for node in nodes:
|
|
||||||
# Process a function or a typedef.
|
|
||||||
params = None
|
|
||||||
kind = node.get('kind')
|
|
||||||
if kind == 'function':
|
|
||||||
params = convert_params(node)
|
|
||||||
node_param_str = ', '.join([p.type for p in params])
|
|
||||||
if param_str and param_str != node_param_str:
|
|
||||||
candidates.append(f'{name}({node_param_str})')
|
|
||||||
continue
|
|
||||||
d = Definition(name, kind)
|
|
||||||
d.type = convert_type(node.find('type'))
|
|
||||||
d.template_params = convert_template_params(node)
|
|
||||||
d.params = params
|
|
||||||
convert_return_type(d, node)
|
|
||||||
d.desc = get_description(node)
|
|
||||||
return d
|
|
||||||
|
|
||||||
# Process a compound definition such as a struct.
|
|
||||||
cls = doxyxml.findall(f"compounddef/innerclass[.='{qual_name}']")
|
|
||||||
if not cls:
|
|
||||||
raise Exception(f'Cannot find {identifier}. Candidates: {candidates}')
|
|
||||||
path = os.path.join(self._doxyxml_dir, cls[0].get('refid') + '.xml')
|
path = os.path.join(self._doxyxml_dir, cls[0].get('refid') + '.xml')
|
||||||
with open(path) as f:
|
with open(path) as f:
|
||||||
xml = et.parse(f)
|
xml = et.parse(f)
|
||||||
@ -248,6 +220,60 @@ class CxxHandler(BaseHandler):
|
|||||||
d.members.append(member)
|
d.members.append(member)
|
||||||
return d
|
return d
|
||||||
|
|
||||||
|
def collect(self, identifier: str, config: Mapping[str, Any]) -> Definition:
|
||||||
|
qual_name = 'fmt::' + identifier
|
||||||
|
|
||||||
|
param_str = None
|
||||||
|
paren = qual_name.find('(')
|
||||||
|
if paren > 0:
|
||||||
|
qual_name, param_str = qual_name[:paren], qual_name[paren + 1:-1]
|
||||||
|
|
||||||
|
colons = qual_name.rfind('::')
|
||||||
|
namespace, name = qual_name[:colons], qual_name[colons + 2:]
|
||||||
|
|
||||||
|
# Load XML.
|
||||||
|
doxyxml = self._ns2doxyxml.get(namespace)
|
||||||
|
if doxyxml is None:
|
||||||
|
path = f'namespace{namespace.replace("::", "_1_1")}.xml'
|
||||||
|
with open(os.path.join(self._doxyxml_dir, path)) as f:
|
||||||
|
doxyxml = et.parse(f)
|
||||||
|
self._ns2doxyxml[namespace] = doxyxml
|
||||||
|
|
||||||
|
nodes = doxyxml.findall(
|
||||||
|
f"compounddef/sectiondef/memberdef/name[.='{name}']/..")
|
||||||
|
if len(nodes) == 0:
|
||||||
|
nodes = self._file_doxyxml.findall(
|
||||||
|
f"compounddef/sectiondef/memberdef/name[.='{name}']/..")
|
||||||
|
candidates = []
|
||||||
|
for node in nodes:
|
||||||
|
# Process a function or a typedef.
|
||||||
|
params = None
|
||||||
|
kind = node.get('kind')
|
||||||
|
if kind == 'function':
|
||||||
|
params = convert_params(node)
|
||||||
|
node_param_str = ', '.join([p.type for p in params])
|
||||||
|
if param_str and param_str != node_param_str:
|
||||||
|
candidates.append(f'{name}({node_param_str})')
|
||||||
|
continue
|
||||||
|
elif kind == 'define':
|
||||||
|
params = []
|
||||||
|
for p in node.findall('param'):
|
||||||
|
d = Definition(p.find('defname').text, 'param')
|
||||||
|
d.type = None
|
||||||
|
params.append(d)
|
||||||
|
d = Definition(name, kind)
|
||||||
|
d.type = convert_type(node.find('type'))
|
||||||
|
d.template_params = convert_template_params(node)
|
||||||
|
d.params = params
|
||||||
|
convert_return_type(d, node)
|
||||||
|
d.desc = get_description(node)
|
||||||
|
return d
|
||||||
|
|
||||||
|
cls = doxyxml.findall(f"compounddef/innerclass[.='{qual_name}']")
|
||||||
|
if not cls:
|
||||||
|
raise Exception(f'Cannot find {identifier}. Candidates: {candidates}')
|
||||||
|
return self.collect_compound(identifier, cls)
|
||||||
|
|
||||||
def render(self, d: Definition, config: dict) -> str:
|
def render(self, d: Definition, config: dict) -> str:
|
||||||
text = '<div class="docblock">\n'
|
text = '<div class="docblock">\n'
|
||||||
text += render_decl(d)
|
text += render_decl(d)
|
||||||
|
Loading…
Reference in New Issue
Block a user