Add file descriptions to (almost) all the qml files.
ClosedPublic

Authored by woltherav on Sep 6 2018, 6:32 PM.

Details

Summary

I am trying to read the qml files, and figured that while I was going through it, I might as well add some class descriptions.

My main concern was making links between the different qml files, as there seem to be some files that are completely unused.

I refrained from documenting the inside declarations too much as I am not very good with qml yet, nor understand if this is a preferable manner of documenting.

Diff Detail

Repository
R157 Peruse
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.
woltherav requested review of this revision.Sep 6 2018, 6:32 PM
woltherav created this revision.
leinir added a comment.Sep 7 2018, 7:40 AM

Good initiative, and a great way to get to both get to grips with things and wrap your head around it at the same time! I must adopt this method ;)

There are indeed a few unused QML files (which could probably be cleaned up for clarity's sake), such as the older tiles, which were used when there was much more information in the list, before the first initial release - if you want to see the most raw early version of "yeah, it can list stuff and read comics, i guess" Peruse, there's a little demo video of it here: https://vimeo.com/147857879 ;)

Documenting deeper parts inside the QML files should not generally be done using doxygen type tags, simply because the QML scoping ensures that those are not accessible from outside those classes. Technically you can get at bits, if they are given an objectName, but generally it is bad style, and breaks encapsulation. The only time you might want to do otherwise is when you encounter a Component, which is specifically something you can use and instantiate inside a page (listview delegates are sometimes done like that).

src/app/qml/Book.qml
291

It holds any instance of ViewerBase, which can be either the Okular viewer (the fallback one), or one of the type specific ones (which right now means the ImageBrowser based ones, but would in the future be joined by a third one, which would do the viewport based navigation)

src/app/qml/PeruseMain.qml
47

It only shows on when the current page is a book, and like in all Kirigami apps, that is on the right hand side of the application :)

src/app/qml/Store.qml
33

to get comics from the KDE Store

src/app/qml/WelcomePage.qml
31

opens

leinir requested changes to this revision.Sep 7 2018, 7:41 AM

(sorry, forgot to mark as request changes)

This revision now requires changes to proceed.Sep 7 2018, 7:41 AM
woltherav marked an inline comment as done.Sep 7 2018, 7:57 AM

Ok, did this locally, also removed doxygen tags inside the qml. will commit when my laptop has internet again.

woltherav updated this revision to Diff 41151.Sep 7 2018, 1:01 PM

Update with docs.

This revision was not accepted when it landed; it landed in state Needs Review.Sep 8 2018, 12:44 PM
This revision was automatically updated to reflect the committed changes.