D21281: [RFC] Write a bit Documentation for Part and PageView

[David Hurka]

davidhurka added a comment.


  Got an overview of open-a-document methods in the Detailed Description of Part. Helped me a lot, can it stay there?
  
  I made some method descriptions a bit more robust to future changes (I think) by making them more abstact and focusing a bit more on the intention.
  
  Also got a thought that the class documentation should deal with the intentions, and less with the implementation. Thanks for your critics, Albert.

INLINE COMMENTS

> part.h:191
> +         * @param url Path to the document file.
> +         * @param page The number of the page, where 1 is the first page.
> +         *

What if the fragment of the URL contains a page number?

> part.h:739
> +         */
>          void errorMessage( const QString &message, int duration = 0 );
> +

A duration of 0 milliseconds seems a bit short to me. Why is this default?

> part.h:773
> +         */
>          bool aboutToShowContextMenu(QMenu *menu, QAction *action, QMenu *contextMenu);
> +

This is a function, but sounds like a signal. How about “addBookmarkActions”?

> part.h:780
> +         * If @p page is not nullptr, there will be a section with title "Page N",
> +         * where N is the page number of @p page. It will contain bookmark and view actions specific to that page.
> +         *

One view action is “Fit Width”. Unlike Fit Width from the menu bar, this Fit Width will not only set the zoom to Fit Width, but also set the view mode to Single Page, and center the viewport on page N.

> davidhurka wrote in part.h:644
> This opens a context menu for context menu items, or what?
> 
> It accepts events of type ContextMenu, that’s clear. To open the context menu, it seems to need a QMenu as event source.

Seems like it opens a context menu for bookmark entries in the Bookmarks menu, to rename or delete a single bookmark. But such a menu does not open in my Okular.

> davidhurka wrote in part.h:647
> Uh-oh, this is complicated. Would someone look over it?
> 
> Yes, the language is not final.

Should be OK now, also improved language.

REPOSITORY
  R223 Okular

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

To: davidhurka, #okular
Cc: aacid, okular-devel, joaonetto, tfella, ngraham, darcyshen
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.kde.org/pipermail/okular-devel/attachments/20190529/a017d82a/attachment-0001.html>