Add documentation to the QtQuick and ContentList plugins.
ClosedPublic

Authored by woltherav on Sep 4 2018, 11:35 AM.

Details

Summary

This adds some documentation strings to the header files in the ContentList folder and the QtQuick folder.

TODO entries were put wherever I just had no clue what a function or the like did, meaning they are actually a little more in need of having docs than any of the other things :D

Diff Detail

Repository
R157 Peruse
Lint
Lint Skipped
Unit
Unit Tests Skipped
woltherav requested review of this revision.Sep 4 2018, 11:35 AM
woltherav created this revision.
woltherav edited the summary of this revision. (Show Details)Sep 4 2018, 11:39 AM
leinir requested changes to this revision.Sep 4 2018, 12:35 PM

That's a whole lot of documentation for some, granted, not always particularly pretty bits of logic! Some bits are misinterpreted or misunderstood, so if you wouldn't mind terribly fixing those, i'd appreciate it :)

src/qtquick/ArchiveImageProvider.cpp
67

the loadFromData function sort of already handles that, but yes, might make sense to add a check to ensure what it's trying to load is image data :)

src/qtquick/ArchiveImageProvider.h
31

That's not what this is used for - it's used to provide images to Qt Quick for the pages in archives (and similarly ACBF) for actually viewing the book. Cover images (which is what PreviewImageProvider deals with) are unrelated to this imageprovider subclass :)

src/qtquick/BookDatabase.h
29

That it's SQL is less important (that's sort of exposing implementation over concept), the point of the class is to provide a cache of known books, to reduce the amount of time spent searching for books on application startup

44

"a list of all known books"

48

"Add a new book to the cache" or somesuch?

src/qtquick/BookListModel.h
34

It uses QQmlParseStatus to ensure that loading the cache of books is postponed until the application UI has been painted at least once.

39

implementation-specific detail, it's enough to mention it's a cache :)

76

sql again :)

106

(detail, whitespace, wouldn't mention it if there weren't other things ;) )

126

A random note on terminology, just 'cos and whatnot - signals "fire", they don't trigger - slots are triggered by signals firing :)

src/qtquick/BookModel.h
108

Very implementation detailed there, QAbstractListModels are incapable of handling tree data, so it seems like it would make sense to just say it gives the number of pages in the book :)

src/qtquick/CategoryEntriesModel.h
59

Just to give a sort-of-context to this: Consider a filesystem, where you navigate through directories which contain either directories or files. Directories are also files, and that's what's going on here, conceptually - it's a little awkward on the code side, because while the data is not quite the same, that's how narrowing down inside categories is done in the UI

113

not for duplicates, it's used for sorting

src/qtquick/FolderBookModel.h
32

A touch implementation-specific, there... this is how /all/ books remember the current page, though, so if it needs mentioning, it needs to go in the book model's setCurrentPage function (which specifically has a flag to update the filesystem, which then uses KFileMetaData to store that information using xattr)

40

"or alternatively the name of a file inside the folder containing the images making up the book" (it supports both)

src/qtquick/PeruseConfig.h
45

"the location of Peruse's KNewStuff configuration file" - reason being this isn't reasonably possible to discover from with QML :)

113

"so the information is not lost when files are moved around outside of Peruse" - the whole point of using xattr rather than just storing information in a database is to avoid information being lost when files are moved (as those attributes are moved along with files, at least on systems and filesystems where it's supported)

This revision now requires changes to proceed.Sep 4 2018, 12:35 PM
woltherav updated this revision to Diff 40982.Sep 4 2018, 1:14 PM
woltherav marked 16 inline comments as done.

Changed "Triggers" to "Fires" and addressed all the comments.

And of course, marking the comments as done.

src/qtquick/CategoryEntriesModel.h
59

I've tried to make something out of this. I am not sure, do categories then hold the ability to hold other categories?

src/qtquick/FolderBookModel.h
32

I have to admit I had trouble with this, because I couldn't figure out how to open a folder of images as a book on my device...

leinir accepted this revision.Sep 4 2018, 1:31 PM

Great stuff, thank you! :)

src/qtquick/CategoryEntriesModel.h
59

Yes, categories are able to hold subcategories (at the moment the only thing which uses that functionality is the folder based filter, but i'm imagining we might want to do something useful there with series, for example, where you might have a series with multiple set sub-stories or somesuch...)

This revision is now accepted and ready to land.Sep 4 2018, 1:31 PM
This revision was automatically updated to reflect the committed changes.