D26918: Improve KNotification API docs

[Aleix Pol Gonzalez]

apol added a comment.


  +1 on improving the documentation, it does read dated. Thanks!

INLINE COMMENTS

> knotification.h:44
>   * @li Feedback events:
> - * For notifying the user that he/she just performed an operation, like maximizing a
> - * window. This allows us to play sounds when a dialog appears.
> - * This is an instant notification.  It ends automatically after a small timeout.
> + * Informs the user about an event that occured, e.g. a music player switched the current track.
> + * It ends automatically after a small timeout.

This entirely changes the semantics. Might still be correct but it could make sense to make sure that's the case?
At least, for an action the user triggers should still be a feedback event, right?

> knotification.h:48
>   * @li persistant notifications:
> - * Notify when the user received a new message, or when something else important happened
> - * the user has to know about.  This notification has a start and a end.  It begins when
> - * the event actually occurs, and finishes when the message is acknowledged or read.
> + * Notify the user about an event that is important (e.g. the laptop's battery is running out)
> + * or requires user interaction (e.g. a pairing request that needs to be accepted/rejected).

persistence is not about being important. It's because it stays relevant over time, which ironically the battery example kind of feels weird because over time the laptop will just run out of juice.

> knotification.h:58
>   * in a QStandardPaths::GenericDataLocation directory.
>   * On Android, this path is <em>qrc:/knotifications5/</em>.
>   *

It could make sense to specify the cmake syntax to do that?

`install(FILES appname.notifyrc DESTINATION ${KNOTIFYRC_INSTALL_DIR})`

REPOSITORY
  R289 KNotifications

REVISION DETAIL
  https://phabricator.kde.org/D26918

To: nicolasfella, #frameworks, broulik, jucato
Cc: apol, kde-frameworks-devel, LeGast00n, cblack, GB_2, michaelh, ngraham, bruns
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.kde.org/pipermail/kde-frameworks-devel/attachments/20200216/3d71b5d4/attachment.html>