 |
 |
 |
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
|

|
|
|