[DRAFT ISSUE] Discussing changes to the Frameworks Documentation Policy
This concerns https://community.kde.org/Frameworks/Frameworks_Documentation_Policy.
This is a list of additions or changes to how we document KDE Frameworks documentation.
CONFIRMED CHANGES
-
QtQuick.Controls.Type instead of QQC2.Type (full names, especially from tags files) -
Use <a>
for external websites, e.g. in @see -
points to, pushes, deletes, acts as, returns whether (present tense); exceptions: is emitted when, should be added before/after, is set to -
Use X for Y (imperative for recommendations, guidelines and rules) -
@c {true,false} (constants) -
@p flags (inline parameters) -
@param flags Description for flags (parameter listing) -
default: DefaultValueOrBinding
(no dots at the end) -
@include (examples) -
@property Type (to change the type) -
Wrap at 80 chars (Settings -> Configure Kate -> Editor -> Show vertical lines ) -
Abbreviations are always UPPERCASE (URL, JSON), file types are always .dotlowercase (.qml files) -
Use @ instead of \ -
Don't use // just before code if it's supposed to be documented, otherwise the code is not parsed by Doxygen -
Use @link only for the rare cases we want to enforce a more useful name, e.g. @link Kirigami.PlatformTheme Kirigami.Theme @endlink -
Newline after @code & @endcode when there is more doc after it -
4 spaces everywhere -
Use @property flags propertyName to document property holding a combination of flags -
Use @property enum propertyName or just @property enum propertyName
CHANGES TO DISCUSS
- Always use @brief to ensure good one-line descriptions, even if it's one line
- Use "holds" for getters, "sets" for setters, and "specifies" where it sounds more natural
- Avoid "tells", "says"
- Generally avoid contractions (don't -> do not)
- Start Doxygen parameters with Caps (@brief Beginning of description)
- Example code should be runnable as is
- :: for C++, . for QML
- Avoid latin expressions unless the text becomes too long, like e.g. -> for example/instance, i.e. -> in other words, to summarize,
CHANGES TO FIGURE OUT
- Use the links provided in the tags file (explain this also)
- //TO-DO or @todo?
- Example code should in most cases not hide anything (when?)
- Required parameters?
- Single or double ´ ?
PROPOSAL FOR DOC ORDERING (draft, let's make this complete)
Documenting classes:
- @brief
- Extra description etc.
- @see
- [NEWLINE] - if next tag is @code
- @code & @endcode NEWLINE
- [@author]
- @since
- @inherit
And properties:
Edited by Thiago Sueto