The fact that these APIs were not documented in the Symbian Developer Library published with the SDK was a hint that the API was not public. But this was not definitive because not all the APIs intended for public use were so published. So developers have had to resort to guesswork.

It was to address this problem that the API tagging project was embarked upon. Under this, every public API is marked in its header file (and indeed in its implementation source file) with two tags governing its release status and its access status (intended audience). Astute SDK users will have observed that these tags have started to appear in header files since v7.0s.

Not only this, a Doxygen-based documentation system has also been introduced and each API is now documented in its source file with Doxygen-style comments which explain the usage of the API.

The project has now effectively been completed with the great majority of the legacy APIs now tagged and documented and a process in place whereby new APIs can only be incorporated into Symbian OS if they are so tagged and documented. The significance of this is not so much the public visibility of API status and usage that this provides for SDK users, as the fact that the tagging is now being used to drive the building of the Symbian Developer Library and indeed the SDKs themselves.

In the first instance, when a version of the Developer Library is built for distribution on an SDK, only those APIs marked as @publishedAll (see below) are documented. Secondly, the documentation in the API reference is not written separately, with the possibility of mistakes and inconsistencies, but picked up dynamically from the in-source documentation comments. Thirdly, any APIs which are not marked as @released are flagged up with a warning to avoid deprecated or prototype APIs being used in error.

For reference the access status tags include:

@internalTechnology

@internalComponent

@internalAll

@publishedPartner

@publishedAll

Of these only the last are intended for usage by third party developers. Symbian Platinum Partners licensing the Symbian OS Development Kit also have access to the @publishedPartner APIs. A large amount of effort is invested to ensure these APIs remain binary and source compatible across OS releases. The other APIs are intended for internal usage within Symbian. Varying degrees of control are exercised over binary and source compatibility for these, depending on the tag.

Release Status tags include:

@prototype

@interim (a deprecated synonym of @prototype)

@released

@deprecated

@removed

@test

The intended life cycle of an API is that it may be released immediately or introduced in the first instance as a prototype subject to subsequent change (prior to full release) or removal. After release, an API may be deprecated or removed. An API may remain as deprecated for an indefinite time before its ultimate removal, but will not be re-released. Test code is marked from the outset as such and of course remains so, but is unlikely to be seen on SDKs.

The simple rule here is: for production code, avoid using anything but @released APIs. You may be able to port code developed using legacy SDKs against APIs which are now @deprecated to a newer version of Symbian OS. But you should look to update your code at the first opportunity to use newer APIs which should have been introduced to replace those deprecated.