Method genRequirements

scripts/docgenerator.py:176–229

Generate text showing what core versions and extensions introduce an API. This relies on the map in apimap.py, which may be loaded at runtime into self.apidict. If not present, no message is generated. - name - name of the API - mustBeFound - If True, when re

(self, name, mustBeFound = True, indent = 0)

        OutputGenerator.endFeature(self)

    def genRequirements(self, name, mustBeFound = True, indent = 0):
        """Generate text showing what core versions and extensions introduce
        an API. This relies on the map in apimap.py, which may be loaded at
        runtime into self.apidict. If not present, no message is
        generated.

        - name - name of the API
        - mustBeFound - If True, when requirements for 'name' cannot be
          determined, a warning comment is generated.
        """

        if self.apidict:
            if name in self.apidict.requiredBy:
                # It is possible to get both 'A with B' and 'B with A' for
                # the same API.
                # To simplify this, sort the (base,dependency) requirements
                # and put them in a set to ensure they are unique.
                features = set()
                # 'dependency' may be a boolean expression of extension names
                for (base,dependency) in self.apidict.requiredBy[name]:
                    if dependency is not None:
                        # 'dependency' may be a boolean expression of extension
                        # names, in which case the sorting will not work well.

                        # First, convert it from asciidoctor markup to language.
                        depLanguage = dependencyLanguageComment(dependency)

                        # If they are the same, the dependency is only a
                        # single extension, and sorting them works.
                        # Otherwise, skip it.
                        if depLanguage == dependency:
                            deps = sorted(
                                    sorted((base, dependency)),
                                    key=orgLevelKey)
                            depString = ' with '.join(deps)
                        else:
                            # An expression with multiple extensions
                            depString = f'{base} with {depLanguage}'

                        features.add(depString)
                    else:
                        features.add(base)
                # Sort the overall dependencies so core versions are first
                provider = ', '.join(sorted(
                                        sorted(features),
                                        key=orgLevelKey))
                return f"{indent * ' '}// Provided by {provider}\n"
            else:
                if mustBeFound:
                    self.logMsg('warn', f'genRequirements: API {name} not found')
                return ''
        else:
            # No API dictionary available, return nothing
            return ''

    # Determine whether an API should be deprecated based on whether it is
    # vendor/core/EXT/KHR and whether the thing deprecating it is