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

Replace \qmlclass with \qmltype and \instantiates

    XMLWordPrintable

    Details

    • Type: Task
    • Status: Closed
    • Priority: P2: Important
    • Resolution: Done
    • Affects Version/s: None
    • Fix Version/s: 5.0.0
    • Component/s: Documentation
    • Labels:
      None
    • Commits:
      17534347d3a1fb1cde171b50a7f6fe0cb73da30a, bd8de220dac8ae1a60c09e809a07daa9f0dfa50f

      Description

      Currently, QDoc assumes things about the \qmlclass command that causes errors
      or misinforms about the true nature of the QML type.

      Example usage: "\qmlclass Item QQuickItem"

      For example, we advise that QML types have two arguments to the \qmlclass, one
      for the type name, and the other is for the C++ class implementation. For
      several cases, the second argument is not needed. This causes ambiguity about
      the intention of author and the necessity of the second argument. In practice, QDoc uses the second argument to check the C++ documentation for properties.

      Cases for different QML types:
      a)there is a C++ class, so the second argument is needed
      b)there is no C++ class, so the second argument is not needed (for example, components)
      c)there is a C++ class, but may or may not have a second argument

      Our proposal is to:
      1)rename "\qmlclass" to "\qmltype"
      2)add a command called "\instantiates" with the C++ class the argument

      Proposal 1 addresses the terminology inconsistencies. We decided on "QML type"
      as the official term before and never implemented it in QDoc.

      Proposal 2 makes the C++ class information as a "context command", adding
      additional information to the QML type documentation. Other context commands
      include \since, \inherits, and so on. We settled on a context command as
      we can avoid the ambiguity by explicitly tagging the QML type as a type that
      is implemented by a C++ class. Another argument is that it reduces the logic
      behind qmlclass, reducing bugs and confusing errors.

      Examples:
      \qmltype Item
      \instantiates QQuickItem

      \qmltype Button

      Of course, we will go through the documentation and change them ourselves.
      *We will do the changes to the documentation and the manual, so you don't have to.*

      Tasks for the doc team:
      -implement change in QDoc, but gracefully deprecate the \qmlclass by giving
      a warning about using \instantiates instead.
      -go through the modules and change the documentation. Notify the maintainer.
      -send email to the affected maintainers.

        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

                There are no open Gerrit changes