Nokia - Connecting People
Secure Internal Wiki

  SWiki  --  MRTSWiki  
  MRTSWiki - ApiDocumentationReviews   

API Documentation Review findings (set received August 9)

General comments

Generally, the documentation as such for each function is in very good shape and I'm really happy with the documentation as such. I'm also very happy with the amount of examples delivered with the documentation set. The process to finalize the documentation is a question of doing some finetuning and should not be a significant effort.

NGI Specific Information

The documentation set that goes to SDK should not have any mentions about NGI. This must be solved before releasing the documentation for the S60 public SDK.

[shakila] - We have checked for NGI keyword in the complete documentation. 'ngi-images' folder is also removed in wk33 release.

How to use MRT

It is strongly recommended to have sections how to use MRT in general in order to answer following questions:
  • How do I interface a library or code written in Standard C with Symbian application? E.g. how do I deal with string conversions?
  • How I do the exception handling?
  • How I do a good C++ wrapper for a C library?
  • How do I call Symbian C++ code from a middleware component?

Good ideas what to document can be found in http://swiki.nokia.com/MRTSWiki/MRTHOWTOPlan

[shakila] - We need to work more on this section

Capabilities

Information about required capabilities must be improved. A statement like "Note: ALL -Tcb indicates that libc APIs have all possible capabilities except the Tcb capability. Tcb grants acesss to the Sys and Resources directories in the phone." is not acceptable from SDK point of view - it documents the capabilities of the libc DLL, not what the user must have in order to use libc. Please note that very 3rd party application developers will ever get "All-Tcb" capabilities.

Typically, capabilities should be documented that a general set for the full library is given and then, the exceptions to that set is given like in the example below:

Required capabilities:
WriteDeviceData, NetworkServices <---- this is for the full library

Exceptions:
In addition to WriteDeviceData and NetworkServices the two CSIPConnection::SetOptL functions require:
NetworkControl, Location, ReadDeviceData <---- this is one exception to the general rule

NOTE! For libc, it would be good to divide the capability information into the used division. See libc comments for more details.

[shakila] - capabilities section, as suggested above will be added under each libc domain. We can discuss more on this

libc

LSB (Linux Standards Base) 3.1 specification must be used when classifying the functions. See http://s60wiki.nokia.com/S60Wiki/Mobile_runtime_documentation and the .chm documentation for the used division. Also, see http://refspecs.freestandards.org/lsb.shtml#LSB_3_1_0 for more details.

The proposed division (as in the .chm) is:
  • System Calls
  • Standard I/O
  • Localization Functions
  • Socket Interface
  • Wide Character
  • String Functions
  • IPC Functions
  • Regular Expressions
  • Character Type Functions
  • Time Manipulation
  • System Database
  • Standard Library

Missing documentation entries

  • acct
  • fpathconf (the index did not point to any .html document)
  • setrlimit
  • sethostname
  • strsignal (pseoudofunction, but without entry)
  • fdatasync (missing in index)
  • getchar_unlocked (missing in index)
  • gets (missing in index)
  • initgroups (missing in index)
  • lchown (missing in index)
  • putchar_unlocked
  • sched_getpriority_max (missing in index)
  • sched_get_priority_min
  • sched_yield
  • setbuffer
  • setgroups
  • setjmp
  • setlinebuf - NOTE! This is not specified by LSB, but documented in man pages. Implementation exist.

[shakila] - Technical writers are working on this. Wk34 release will have updated documentation entries.

Failing entries

The documentation of the index function (part os string functions) points to the zlib index (which has the same name as the documentation for the index function).

[shakila] - This is fixed in wk33 release

Pseudo Functions

This is very important information as such, but the category as such is wrong, because there are also Posix threads functions in this section. It should be on the same level as the listing of the libraries named and the naming can be "Pseudo Functions".

Another issue - ALL pseudo functions must be documented with the known Symbian specific limitation. No need to give example code for pseudofunctions because you are not supposed to use them - there is no need to promote usage of these.

It is also important that usage of pseudo functions cannot lead to unexpected behaviour from program logic point of view. This must be checked with responsible developers.

Capabilities required for using libc

It makes sense to document capabilities for below areas separately, because the below areas require very different capabilities. For example standard I/O, some usage require AllFiles capabilities depending of the location of the processed file according to platform security. Also, socket interface usage require typically NetworkServices.

  • System Calls
  • Standard I/O
  • Localization Functions
  • Socket Interface
  • Wide Character
  • String Functions
  • IPC Functions
  • Regular Expressions
  • Character Type Functions
  • Time Manipulation
  • System Database
  • Standard Library

Other issues

  • libc index has pointers to crypt, setkey and encrypt functions.
  • mkstemp spelled as mktemp in libc index.
  • munlockall specified in index, no implementation however is coming.
  • strlcat and strlcpy implemented, no documentation
  • sync documented, no implementation however

[shakila] - This will be updated in wk34 release

libm

There is no need to divide functions into arithmetic and mathematical functions (the LSB does not do that).

fpclassify - missing in libm index entries
ieee - missing in libm index entries

It would be good to mention in the libm overview documentation in the first bullet in the limitation section that even if long double is not supported, methods are documented for reference.

The documentation of gamma functions has strange small fonts which are not supported by the stylesheet.

libz

Alignment for some of the documented functios are centered and not left aligned. This is a problem with the some of the .html files for libz.

Correct format (like in deflateparams.html)

<h2 style="text-align: left;">Examples</h2>

Incorrect format (like in deflatereset.html)

<h2>Examples</h2>

[shakila] - This is corrected in wk33 release

Naming of .html files for zlib - it is enough to have the name of the function like alder32.html etc. No need to put zlib in front of the name.

[shakila] - We have retained the filenames as it was downloaded. Other than adler32.html, other files are preceded with zlib.

libpthread

Following functions are missing in the index:
  • pthread_attr_setschedparam
  • pthread_mutexattr_destroy
  • pthread_mutexattr_settype
  • pthread_mutexattr_gettype
  • pthread_mutexattr_getpshared
  • pthread_mutexattr_setpshared

Glib

Use the styleApiDesc.css in all glib documents.

Open: documentation on GObject here? Should it have it's own entry or should it be a subcategory to glib documentation?

Documentation of needed capabilities? Typically, usage of Glib functions don't require any capabilities, but is must anyway be mentioned.

Missing library information (what library to link against).

Sorting of glib index.

What do some "Unix" specific functionality do in Symbian, like g_get_real_name, g_thread_join etc? This must be documented as well.

Very little example code how to use GLib. This could be improved.

GObject

Use the styleApiDesc.css in all gobject documents.

Documentation of needed capabilities? Typically, usage of GObject functions don't require any capabilities, but is must anyway be mentioned. There are however exceptions, like file handling functionality.

Missing library information (what library to link against).

[shakila] - changes are in progress

libssl

No documentation available.

libcrypto

No documentation available.

[shakila] - libssl and libcrypto documentation was integrated in wk33 release.

Developing Applications in Open Environment

In the public SDK documentation, following topics are not allowed:
  • How to build an MRT Library
  • Guidelines for writing an MRT library

[shakila] - removed these sections in wk33 release

File Naming

Many standard functions have the same documentation in the same .html file (like acos, acosf and acosl). From documentation generation point of view, it would be better if those would have own filenames like:
  • acos.html
  • acosf.html
  • acosl.html

with the same content. If not done in this way, it will either screw up the .chm file or the Eclipse documentation plug-in.

NOTE! The above does not apply to glib or gobject documentation.

[shakila] - We are planning to use script to generate this info in the required API html pages. Will explain during our telco.

API Specifications in XML

These are not really needed as is, lot of useful material in .html format exist which can be used in the documentation.

As background information, when API reference documentation is generated, XML based API specs are converted to .html and these .html documents are used when the help is generated. We can directly deliver documentation in .html format.

Alphabetical index

The index should be common for all libraries, not divided into libraries (comment from Mika Rytkönen).

NOTE! Both versions will be available:
  • index/library and
  • one common index accessible from the "Index" tab in the .chm file.

The common index requires however that a file, index.hhk is generated with following content (the below is only an example and the complete file must contain all function entries provided by MRT):

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<HTML><HEAD></HEAD><BODY>
<OBJECT type="text/site properties">
<param name="FrameName" value="right">
</OBJECT>
<UL>
<LI><OBJECT type="text/sitemap"><param name="Local" value="acos.html"><param name="Name" value="acos"></OBJECT>
<LI><OBJECT type="text/sitemap"><param name="Local" value="asin.html"><param name="Name" value="asin"></OBJECT>
<LI><OBJECT type="text/sitemap"><param name="Local" value="atan.html"><param name="Name" value="atan"></OBJECT>
<LI><OBJECT type="text/sitemap"><param name="Local" value="glib-Arrays.html#id3236077"><param name="Name" value="GArray"></OBJECT>
<LI><OBJECT type="text/sitemap"><param name="Local" value="glib-Asynchronous-Queues.html#id2958288"><param name="Name" value="GAsyncQueue"></OBJECT>
<LI><OBJECT type="text/sitemap"><param name="Local" value="glib-Basic-Types.html#id2880377"><param name="Name" value="gboolean"></OBJECT>
<LI><OBJECT type="text/sitemap"><param name="Local" value="glib-Byte-Arrays.html#id3246357"><param name="Name" value="GByteArray"></OBJECT>
</UL>

This file should be generated by a script - the content does not need to be sorted, this is taken case by the Microsoft Help when the index is created for the first time.

When the .chm API reference is created, the index.hhk file is used when the .chm is compiled together.

[shakila] - We will work on this index.hhk file script.

Comments from Terho Niemi

To Do List

This list would specify all open issues to be done so that everyone can see the status. OK. Done

Documentation of capabilities

Function level documentation of capabilities would be good - however, library (or finer granularity) level capability documentation is also enough.

Return Values

The Return Values section should available immediately after the Synopsis field. This makes the documentation more user friendly if the documentation is long (does not fit to one single page).

[shakila] - This requires man page change or man2html script change. we are working on this.

Name Section

The function name should be followed with one single line description in order to quickly get an understanding what the function does.

[shakila] - This requires man page changes. Planning to include in wk35 release.

Renaming of Libs

libdl, libz etc folders should be renamed to something like Dynamic Linking, Compression etc. NOTE! Also the shortname mentioned in LSB will be used like Compression (libz). OK - done

Gaming APIs

Review of gaming APIs? Gaming APIs will be treated separately and are not part of this review round.

Correctness of documentation

Who will check the correctness of documentation? There are many issues with the documentation set.

Recommended approach is:
  • Developers responsible of the implementation, must review the documentation.
  • Proof reading must be done in order to ensure that correct English is used.
  • This must be done by the Bangalore team.

Missing Return Values

Some function level documentation don't have return values documented even if they certainly return something useful. One typical example is the sprintf function, which returns length of the output (excluding the terminating NUL).

Correctness of examples

Do following apply for documented examples:
  • they have successfully built?
  • they have been successfully executed?

It is crucial that documented example code is correct.



^ Top | # Printable version


Messages
Security notice - Do not add non-existing users to groups as this may lead to information leaks.
More info >>
Properties
Ver - Modified - Modifier:
r1.7 - 21 Aug 2006 - 12:39 - ShakilaSelvaraj

Actions
Edit
Add attachment
Referenced by
Printable version
Diffs | r1.7 | > | r1.6 | > | r1.5
More actions

Search
Go

Navigation
SWiki home
Web home
Recent changes
Web topic list
Web index
Wiki search
Jump to topic

Powered by SWiki

© Nokia 2005 site terms