[Development] Calendar classes: API review request

[Edward Welbourne]

Simon Hausmann (31 July 2018 12:38)
> I've said this also in the reviews, but perhaps it got lost:

'fraid so. It's been a long review ... and gerrit's not good at helping
us find which comments haven't been addressed.

> My primary concern with this API is that it promotes an unclear
> ownership model.

hmm ... this is partly a symptom of most QAbstractCalendar instances
being dataless.  Each calendar has different code to implement its
behaviour.  Or, to put it another way, the vtable is the data.

Admittedly, I can imagine uses for derived classes that do have data
(e.g. for historians of Europe, taking into account the use of Julian
for part of history, Gregorian for other parts, with diverse dates for
the transition - and some foibles in between), so we should make it
possible for them to have data.

> Typically we have API that is either a sub-class of QObject (where the
> parent may delete the children, such as QFile) or we have value based
> classes (such as QDateTime). There is also a slightly less common,
> third model with explicitly shared types, I think mostly acting as
> singletons.

All of which is mostly about how *the data* is shared.

> With QAbstractCalendar there's an entirely new model (which also
> includes a clone() method). I think that model should [be]
> reconsidered,

Can you suggest an alternative ?

> but if not, then it needs to be documented and it needs to be
> clarified how this model applies to the exposure of calendars to
> QML. Otherwise you easily risk creating dangling pointers (as pointed
> out in the QML review).

> A secondary concern is that the API, once submitted, is not
> extensible. We cannot add new properties without breaking binary
> compatibility, due to the use of virtual functions in the frontend.

Again, please suggest some good ways to do this for the case of
calendars, where only rather obscure ones have any data; the differences
among widely-used calendars are all in code.

> I think in the past we've solved this by having a nice front-end API
> with non-virtual functions (those we can add) and channeling this
> through to a backend that uses fewer virtual functions but enums (that
> can be extended) to dispatch.

The problem with that is that you're stuck with the calendars that Qt
ships.  We're never going to ship every calendar that the long tail of
potential users might want.  We can probably manage the dozen-or-two
calendars that the ECMAScript spec mentions in this context, but I want
it to be easy for some minority population to be able to implement their
own calendar and have Qt transparently use it.  The present design
supports that.

As an example of the long tail, AIUI, a fully faithful implementation of
the islamic calendar (as distinct from the fairly widely-adopted "civil"
islamic calendar) needs a distinct calendar for each community.  It
would, IIUC, need data about the user's (community's) local ephemrides
(when, exactly, the full or new moon is seen rising there, each month);
and I want to leave open the option of some population, who want it,
doing that for themselves without us having to take in patches for them
to get what they want.  There are likewise variants of the Julian
calendar still in use by some communities - each its own variant - and I
want to let them do their thing in their diverse own ways without us
needing to take in patches.  Then, as alluded to above, there's the
historians ...

> Another alternative is the extension mechanism that we've used with
> QFile/QIODevice.

I don't know that one.  I just know that there's a bewildering tangle of
abstractions behind QFile, seemingly to handle different file systems,
that I sometimes manage to make enough sense of to fix things.  I hope
we can avoid having such vast complexity for calendars.  They're not
(individually) actually that complicated (well, except for France and
Sweden a couple of centuries ago); its the variations between them that
complicate life.

All of the extension mechanisms you talk about depend on us writing yet
another back-end for each supported case.  With calendars, it must be
possible for some community to support its own, without needing us to
know about it or do more than provide the infrastructure theirs slots
into.


So yes, the thing I neglected to mention in my previous mail is: do we
have any suggestions for how to design an API that'll let app authors
implement the calendars they want to support (for their possibly very
minority user-bases) and have them work transparently with Qt, just as
well as any other calendar that we support ?  Bonus points if there's a
way for app-authors to implement a plugin API that lets several of them
share the same plugin-implemented calendars (without us having to care
how they do it).  The present design does support all of that.
Using a classic (but not-so-Qt-ish) C++ virtual method API.

	Eddy.