Uploaded image for project: 'Qt'
  1. Qt
  2. QTBUG-121481

QDoc: Make overload number independent of parsing order

    XMLWordPrintable

Details

    • Task
    • Resolution: Fixed
    • P2: Important
    • 6.8.0 FF
    • None
    • Build tools: qdoc
    • None
    • 2e91339b0 (dev), 601d188ca (dev), 9e8353bbb (dev)
    • DaVinci 93

    Description

      When QDoc parsers a project, it build an intermediate representation of certain elements in the code-base of the project, which is later used to perform sanity checks on the documentation and to extract the required information to build the output documentation set.

       

      When parsing a code-base that has some C++ code, QDoc extract information about all functions.

       

      When working with overload sets, QDoc assigns them a number, the "overload number", to distinguish them.

       

      The overload number of function in an overload set impacts certain aspect of the output documentation set, such as the order in which the member of the overload set are presented.

       

      Currently, each time QDoc encounters a function it build a `Node` to represent it internally. When a function is found to be an overload of an already registered function, the built `Node` is registered as an overload of the original registered function, and appended into a linked list that whose head is the `Node` representing the original member of the overload set that was registered.

       

      After all the parsing is done, the linked list is traversed, and an increasing number is set as the "overload number" for each member of the overload set.

       

      The order of the linked list is, due to this implementation, is dependent on the order in which QDoc reads the function from the code-base.

       

      That is, if file A presents function F and file B present function F1, where F and F1 are part of the same overload set, if file A is read before file B, F will have overload number 0 and F1 will have overload number 1.

      If B is read before A, the opposite will be true.

       

      As part of optimizing the current performance of QDoc, we expect files to be read in a non-deterministic order.

      With overload numbers being order dependent, this would mean that multiple runs of QDoc over the same code-base would be able to produce different results.

       

      To avoid the issue, overload numbers should be made independent of read order.

       

      To do so, the list of overloads in an overload set should be ordered by QDoc before the assignment of overload numbers is performed.

       

      An order can be given to an overload set based on the lexicographic order of their argument.

      For function that result equal under this criteria, a more specific order should be given by taking into consideration properties such as its reference qualifiers or its constness.

       

      A special care should be given to function which QDoc marks "internal" (not to be shown in the output documentation).

      Due to certain thwarts of the current implementation, "internal" `Node`s should always be put at the end of the list of overloads for an overload set.

       

      This can be done as part of the necessary sorting, by considering "internal" `Node`s to always have less priority.

      Attachments

        Issue Links

          No reviews matched the request. Check your Options in the drop-down menu of this sections header.

          Activity

            People

              treinio Topi Reiniö
              diseraluca Luca Di Sera
              Votes:
              0 Vote for this issue
              Watchers:
              2 Start watching this issue

              Dates

                Created:
                Updated:
                Resolved:

                Gerrit Reviews

                  There are no open Gerrit changes