[lsb-discuss] Qt 4 decision
Alexey Khoroshilov
khoroshilov at ispras.ru
Wed Sep 5 23:01:18 PDT 2007
Hi Jesper,
>
> I don't really see the need for documentation of the destructors; It's a bit
> redundant to repeat "this deletes the object".
Yes, I agree. That is why I listed them separately.
> Concerning the meta-related interfaces, they are used by the moc - for the
> signals and slots, and thus not requiring documentation as well.
Actually documentation of 4 methods and static fields in the QObject
would be enough to cover all the "Meta" sheet.
QObject::staticMetaObject
QObject::qt_metacast(char const*)
QObject::qt_metacall(QMetaObject::Call, int, void**)
QObject::staticQtMetaObject
At the moment it is not documented except for QObject::staticMetaObject,
which is documented starting from Qt4.2. But it is not documented in Qt
4.1, which is referenced in the standard. What shall we do here?
Please note that 2 helper functions are in the "Meta" sheet by mistake:
qt_qFindChildren_helper(QObject const*, QString const&, QRegExp const*,
QMetaObject const&, QList<void*>*)
qt_qFindChild_helper(QObject const*, QString const&, QMetaObject const&)
> However, those regular interfaces mentioned I will take a look at and get back
> to you on.
OK. If we see an undocumented interface the first thought is: Why it is
in the standard if it is even not documented?
May be it is not the case for C++ ABI (in contrast to C ABI) because
even internal C++ methods can be important for binary compatibility.
But there are some static methods and global functions in the list,
which are pretty similar to C functions.
If an interface is reasonable to be standardized we have two situations.
1. If the interface is intended for using by ISVs, the documentation
have to exist.
It have to describe how to use the interface correctly and what is its
functionality.
It is just a question of maturity of an API.
2. If the interface is not intended for using by ISVs but it is required
for achieving binary portability, we have to khow:
- Why is the interface in the standard?
- What are requirements to distributions regarding to the interface?
- What are requirements to applications regarding to the interface?
LSB as a standard contains such descriptions for each included interface
either itself or by linking an external documentation. You can see such
links, for example, in the Description section at the interface homepage
in the LSB Navigator [1].
[1]
http://www.linux-foundation.org/navigator/browse/int_single.php?cmd=list-by-name&Istd=113&Iname=_ZN5QFile6removeERK7QString
--
Regards,
Alexey.
More information about the lsb-discuss
mailing list