Repository: raspberrypi/pico-sdk
File: tools/extract_cmake_functions.py (Python)

Code before:
    "pico_set_printf_implementation",
    "pico_expand_pico_platform",
])

all_functions = {}

# Supported commands:
# \brief\ <brief description, which should be included in the main description>
# \brief_nodesc\ <brief description, which should be excluded from the main description>
# \param\ <parameter_name> <parameter description>
#
# Commands in the middle of a line are not supported
#
# The ; character at the end of a line denotes a hard line break in the description
# The \ character (outside of a command) and the # character are not supported in descriptions
def process_commands(description, name, group, signature):
    brief = ''
    params = []
    desc = ''
    for line in description.split('\n'):
        line = line.strip()
        if line.startswith('\\'):
            command = line.split('\\')[1]
            if command == 'param':
                # Parameter name and description
                params.append(line.split('\\')[2].strip())
            elif command == 'brief':
                # Brief description
                brief = line.split('\\')[2].strip()
                desc += brief + '\\n'
            elif command == 'brief_nodesc':
                # Brief description which should not be included in the main description
                brief = line.split('\\')[2].strip()
            else:
                logger.error("{}:{} has unknown command: {}".format(group, name, command))
        elif '\\' in line:
            logger.error("{}:{} has a line containing '\\': {}".format(group, name, line))
        else:
            desc += line + '\\n'
    # Check that there are no semicolons in the parameter descriptions, as that's the delimiter for the parameter list
    if any([';' in x for x in params]):
        logger.error("{}:{} has a parameter description containing ';'".format(group, name))
    # Check that all parameters are in the signature
    for param in params:
        if param.split(' ')[0] not in signature:
            logger.error("{}:{} has a parameter {} which is not in the signature {}".format(group, name, param.split(' ')[0], signature))
    # Check that the brief description is not empty
    if not brief:
        logger.warning("{}:{} has no brief description".format(group, name))

    return desc.strip(), brief, ';'.join(params)

Review comment (suggestion):
You've got `line.split('\\')[2].strip()` appearing multiple times, so perhaps it's better to do something like:
```python3
_, command, remainder = line.split('\\', 2)
remainder = remainder.strip()
```


Code after:
    "pico_set_printf_implementation",
    "pico_expand_pico_platform",
])

# Group descriptions
group_names_descriptions = {
    'boot_stage2': ('Boot Stage 2', 'CMake functions to create stage 2 bootloaders'),
    'pico_binary_info': ('Pico Binary Info', 'CMake functions to add binary info to the output binary'),
    'pico_btstack': ('Pico BTstack', 'CMake functions to configure the bluetooth stack'),
    'pico_lwip': ('Pico LwIP', 'CMake functions to configure LwIP'),
    'pico_cyw43_driver': ('Pico CYW43 Driver', 'CMake functions to configure the CYW43 driver'),
    'pico_runtime': ('Pico Runtime', 'CMake functions to configure the runtime environment'),
    'pico_standard_link': ('Pico Standard Link', 'CMake functions to configure the linker'),
    'pico_stdio': ('Pico Standard I/O', 'CMake functions to configure the standard I/O library'),
    'pico_pio': ('Pico PIO', 'CMake functions to generate PIO headers'),
    'other': ('Other', 'Other CMake functions'),
}


all_functions = {}

for group, (brief, description) in group_names_descriptions.items():
    all_functions['_desc_{group}'.format(group=group)] = {
        'name': '_desc_{group}'.format(group=group),
        'group': group,
        'signature': '',
        'brief': brief,
        'description': description,
        'params': '',
    }

# Supported commands:
# \brief\ <brief description, which should be included in the main description>
# \brief_nodesc\ <brief description, which should be excluded from the main description>
# \param\ <parameter_name> <parameter description>
# \ingroup\ <group_name>
#
# Commands in the middle of a line are not supported
#
# The ; character at the end of a line denotes a hard line break in the description
# The \ character (outside of a command) and the # character are not supported in descriptions
def process_commands(description, name, group, signature):
    brief = ''
    params = []
    desc = ''
    for line in description.split('\n'):
        line = line.strip()
        if line.startswith('\\'):
            _, command, remainder = line.split('\\', 2)
            remainder = remainder.strip()
            if command == 'param':