Function fixupRefs

scripts/reflib.py:269–397

Fill in missing fields in pageInfo structures, to the extent they can be inferred. - refpageMap - dictionary of pageInfo structures - specFile - filename - file - list of strings making up the file, indexed by pageInfo

(refpageMap, specFile, file)

    return line

def fixupRefs(refpageMap, specFile, file):
    """Fill in missing fields in pageInfo structures, to the extent they can be
    inferred.

    - refpageMap - dictionary of pageInfo structures
    - specFile - filename
    - file - list of strings making up the file, indexed by pageInfo"""
    # All potential ref pages are now in refpageMap. Process them to
    # identify actual page start/end/description boundaries, if
    # not already determined from the text.
    for name in sorted(refpageMap.keys()):
        pi = refpageMap[name]

        # # If nothing is found but an include line with no begin, validity,
        # # or end, this is not intended as a ref page (yet). Set the begin
        # # line to the include line, so autogeneration can at least
        # # pull the include out, but mark it not to be extracted.
        # # Examples include the host sync table includes in
        # # chapters/fundamentals.adoc and the table of Vk*Flag types in
        # # appendices/boilerplate.adoc.
        # if pi.begin is None and pi.validity is None and pi.end is None:
        #     pi.begin = pi.include
        #     pi.extractPage = False
        #     pi.Warning = 'No begin, validity, or end lines identified'
        #     continue

        # Using open block delimiters, ref pages must *always* have a
        # defined begin and end. If either is undefined, that is fatal.
        if pi.begin is None:
            pi.extractPage = False
            pi.Warning = 'Cannot identify start of ref page open block'
            continue

        if pi.end is None:
            pi.extractPage = False
            pi.Warning = 'Cannot identify end of ref page open block'
            continue

        # If there is no description of the page, infer one from the type
        if pi.desc is None:
            if pi.type is not None:
                # pi.desc = pi.type[0:len(pi.type)-1] + ' (no short description available)'
                pi.Warning = 'No short description available; could infer from the type and name'
            else:
                pi.extractPage = False
                pi.Warning = 'No short description available, cannot infer from the type'
                continue

        # Try to determine where the parameter and body sections of the page
        # begin. funcpointer, proto, and struct pages infer the location of
        # the parameter and body sections. Other pages infer the location of
        # the body, but have no parameter sections.
        #
        # Probably some other types infer this as well - refer to list of
        # all page types in genRef.py:emitPage()
        if pi.include is not None:
            if pi.type in ['funcpointers', 'protos', 'structs']:
                pi.param = nextPara(file, pi.include)