Expand the documentation’s main page with an overview and example
ClosedPublic

Authored by jfita on Apr 13 2020, 9:33 PM.

Details

Summary

This may be something that only happens to me, but i find difficult to
use a new library when there is only documentation for each individual class
without a description of how they work together. In this case, between the
example and the fact that the library is not that big, it is relatively easy to
figure things out, but i still believe that it is harder than it could be.

I only modified MainPage.dox to show what are the main classes of KReport and
what are their jobs relative to each other within the library. They are a
cleaned up version of the notes i took while trying to integrate KReport to a
Qt application, so are written from the point of view of a first-time user and
only for these parts that i needed.

This is no excuse for not being knowing how to express things better; sorry for
that.

The code that i have written in the section for how to create plugins and data
sources is only in MainPage.dox because i thought that it would make the sample
application harder to follow if in the examples folder there are code from
multiple applications or libraries, but i certainly have created the projects
to test them all and i could add these files if it seems appropriate.

Diff Detail

Repository
R14 KReport
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.
jfita created this revision.Apr 13 2020, 9:33 PM
Restricted Application added a project: KReport. · View Herald TranscriptApr 13 2020, 9:33 PM
jfita requested review of this revision.Apr 13 2020, 9:33 PM

Very nice, I will review this.

Thanks, reviewed first 200 lines. Good job!

src/Mainpage.dox
31

I'd say The report designer is a visual tool to create report templates by placing items, such as labels or fields, and setting their properties. Not mention QWidget here, it is mentioned in the detailed description of the KReportDesigner below.

37

In memory it's not an XML so I'd not mention XML in this sentence.

I'd say "Report designs are saved as XML documents, and can be stored on any medium for re-use and transfer (memory, file, part of a KEXI database project)".

38

I'd say The KReportDesigner is based on the Qt Graphics View framework.
QWidget is enclosing frame only.

Also terminology: we do not call QWidgets as controls, but just as widgets.

49

... are provided through the plugin system (for extensibility) and implement one or more of the following interfaces:

jfita updated this revision to Diff 80325.Apr 16 2020, 9:53 PM

Updated text according to Jarosław’s notes

I'd say "Report designs are saved as XML documents, and can be stored on any
medium for re-use and transfer (memory, file, part of a KEXI database
project)".

I removed the reference to memory here because, to me, “memory” conveys the
meaning of volatile and not someplace where to store documents. What do you
think?

I removed the reference to memory here because, to me, “memory” conveys the
meaning of volatile and not someplace where to store documents. What do you
think?

Right, good!

Reviewed until line 475.

src/Mainpage.dox
252

extract values of its properties

362

Our coding standards are based on Qt's standards and as such it recommends not using auto in this context. Exception is when operator new is used in the line.

427

Coding standards (Qt and KF based): use if (pointer) and if (!pointer).

jfita updated this revision to Diff 80503.Apr 18 2020, 9:31 PM

Fix wording, and remove improper use of auto and pointer validity according to coding style

staniek added a reviewer: piggz.

Good job, some notes added.

src/Mainpage.dox
528

I would propose to remove all occurrences of QLatin1String() and jsut use raw strings. Reason is, in Qt 5 we would use QStringLiteral() but for the needs of the guide it is better to skip such optimization altogether as it barely helps in GUI apps but costs us the clarity.

BTW: I know we have lots of QLatin1String() in KReport code but this is a library code and also it comes from legacy times. One day we would like to convert to QStringLiteral internally but we do not do that to avoid altering git-blame information too much.

575

buildXML()

605

buildXML()

622

eight small boxes

665

This QObject needs to define Qt properties in order to provide a way to write and read item's property values.

891

The last thing required to implement this interface is *to* create a plugin factory.

893

the Qt MOC

980

Once done, the new plugin should be available for every application using %KReport. In applications that utilize the Report Designer, Items toolbar should also offer the new item type.

986

Propose: separate sentence, not a ';'

997

convention:

explicit KReportTableModelDataSource(QAbstractTableModel *model);

1016

Maybe QPointer<QAbstractTableModel>

1096

It also needs to know the fields count for each record, their names, and a way to reference them.

1122

%KReport will needs to be able to read the value of a given field.

BTW, while creating reviews please add at least me and KReport maintainer Adam as reviewers. Thanks!

jfita updated this revision to Diff 80643.Apr 20 2020, 12:55 PM

Improve wording, remove use of QLatinString/QStringLiteral, and make code follow conventions better

BTW, while creating reviews please add at least me and KReport maintainer Adam as reviewers. Thanks!

Sorry about that. I misunderstood the instructions at the community wiki to mean that it would be done automatically.

I will keep it in mind next time.

staniek added a comment.EditedApr 22 2020, 7:44 PM

BTW, while creating reviews please add at least me and KReport maintainer Adam as reviewers. Thanks!

Sorry about that. I misunderstood the instructions at the community wiki to mean that it would be done automatically.

I will keep it in mind next time.

No problem. I was notified and Adam probably too since we're following the project's changes here but typically when I create a review myself I am adding reviewers by hand too.

Also, reviews would go to https://invent.kde.org (GitLab) later this year. Not sure when.

staniek accepted this revision.Apr 22 2020, 7:46 PM
This revision is now accepted and ready to land.Apr 22 2020, 7:46 PM
This revision was automatically updated to reflect the committed changes.
piggz added a comment.Apr 22 2020, 7:51 PM

Amazing to have someone using my work, can I ask what app you are using it in?

jfita added a comment.May 16 2020, 7:48 PM

Amazing to have someone using my work, can I ask what app you are using it in?

It is a very simple custom application for a local chemist, to do odd jobs that their pharmacy management system does not perform in they way they want to. Starting this week, i use KReport to print reports such as the list of products needed in the pharmacy due to customer demand; nothing fancy.

Thank you for KReport. It is the best Qt-based reporting library i have worked with so far.