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

Give documenter more control of linking

    XMLWordPrintable

    Details

    • Type: Task
    • Status: Closed
    • Priority: P2: Important
    • Resolution: Done
    • Affects Version/s: None
    • Fix Version/s: 5.4.0
    • Component/s: Build tools: qdoc
    • Labels:
      None
    • Technical Risk:
      Normal

      Description

      qdoc isn't generating any collision nodes. This is because qdoc now creates a separate parse tree for each Qt5 module, and at present, the names that would have collided, when there was only one parse tree for all of Qt5, are now always in separate modules. Hence, qdoc never sees them as colliding. But when qdoc searches for a name to satisfy a \l (link), it searches the separate parse trees in an order that is chosen to be most efficient for searching. If the name qdoc is searching for exists in multiple modules, qdoc will find it in one of those modules and then will stop looking. This means that qdoc might create that link to the wrong place, but there will be no qdoc warning about a name collision.

      We have seen a few of these already. The collision node system used in the single-parse-tree qdoc can no longer be used. Instead we will allow the documenter to more completely specify where the link target is and what type of entity it is.

      Currently, the general form of the link command is the following:

      \l <link> <text>

      We will add a new parameter at the front, enclosed in square brackets:
      \l [ <criteria> ] <link> <text>

      <criteria> consists of one to three words separated by blanks, e.g.:
      \l [QtWidgets] <Ambiguous title> <some text>
      \l [QML QtQuick qmlmethod] <some link> <some text>

      The order of the words in the square brackets is not significant. There are three kinds of words.

      1. Entity type.
      This is the kind of thing you are trying to link to. It maps to the list of node types in qdoc. These are the permitted words:

      "class", "qmltype", "page", "function", "property", "variable", "group", "module", "qmlmodule", "qmppropertygroup", "qmlproperty", "qmlsignal", "qmlsignalhandler", "qmlmethod", "qmlbasictype", "enum", "typedef", "namespace"

      So if you are trying to link to a C++ class, but your link goes to a QML type of the same name, then you can add [ class ] at the front of your link command and qdoc will keep looking until it finds a C++ class with the correct name.

      2. Module name
      These are the values of the "project" variable in each qdocconf file, e.g. QtCore, QtQuick, etc. So if your link should got to something in QtQuick, but qdoc is linking to something with the same name in QtGui, you can add [ QtQuick ] to your link command and qdoc will look for the link ONLY in the QtQuick parse tree. I think this option will be most useful.

      3. QML and CPP
      If your link target is a QML entity but qdoc is linking to a CPP entity, add [ QML ] to your link command. Or if your link target is a C++ entity but qdoc is linking to a QML entity, add [ CPP ] to your link command.

        Attachments

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

          Activity

            People

            Assignee:
            gbk Martin Smith (Qt)
            Reporter:
            gbk Martin Smith (Qt)
            Votes:
            0 Vote for this issue
            Watchers:
            2 Start watching this issue

              Dates

              Created:
              Updated:
              Resolved:

                Gerrit Reviews