[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