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

Futher streamline member-swap() documentation

    XMLWordPrintable

Details

    • Task
    • Resolution: Unresolved
    • P2: Important
    • None
    • None
    • Documentation
    • None

    Description

      Following the addition of the \memberswap macro, there remain several inconsistencies even with the macro being used:

      • Several classes use "instance" or "object" suffixes in the \memberswap argument. Decide whether to have these suffixes on all swap() documentations or not, if so, which one, and either move that particle into the macro or remove it from the macro users.¹
      • Some classes use just the class name, but the vat majority of classes uses an English prose version of the type ("string", not "QString"). Fix the users that still use a raw class name.²
      • Different classes use different amount of scope of the class name. For QFooBarBaz, some authors use "baz", others "bar baz" and yet others "foo bar baz" as the \memberswap argument. Create a rule for how much of the class name should be used in the macro argument, document it and adjust the existing users.
      • One of the QMime classes has an extra paragraph. Should something like this be moved into the macro?

      ¹ Use

      git grep -E '\\memberswap\{[^}]+ (instance|object)\}'

      to find instances
      ² Use

      git grep -E '\\memberswap\{Q'

      to find instances

      Attachments

        Issue Links

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

          Activity

            People

              docteam Qt Documentation Team
              mmutz Marc Mutz
              Vladimir Minenko Vladimir Minenko
              Alex Blasche Alex Blasche
              Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

              Dates

                Created:
                Updated:

                Gerrit Reviews

                  There are no open Gerrit changes