[Lsb-infrastructure] t2c-alsa-tests: markup of the spec

[Andrey Tsyvarev]

Stew,

I have looked at the current markup of the ALSA spec.

The markup is mostly OK. By the way, the text specified for the
requirements during markup seems much clearer to me than the original
text of the spec, good work!

Several notes:

1. Some of the marked-up text fragments include tags <p>, <table> or
other tags for formatting of the output. But the markup of
requirements itself is based on the <span class="req"> tag, so the
html code becomes incorrect from the point of view of HTML DTD, and
such code is not highlighted.

Such incorrect html code should be corrected everywhere it is
possible. If a tag like <p>, <table>, <div> occurs within
<span class="req">...</span>, the tag should be removed or moved
outside of <span class="req">...</span>.

It may help if exactly the necessary text fragment is selected with
the mouse while marking up a requirement. That is, while doing this,
do not move cursor to the previous or the next lines, do not move cursor
outside of table cell, etc.

2. Most of the requirements describing parameters of a function are
usually requirements for the applications using the function rather
than for the function itself. Such requirements should be marked up
using "app" prefix in the ID. E.g.,

app.snd_pcm_sw_params_set_start_threshold.02: The 'pcm' parameter shall be the PCM handle.

The requirements of this kind mean that it is the responsibility of
the applications using the function rather than of the function itself
to ensure the requirement holds. A test for the function is a special
case of such application too.

Requirements for the applications and requirements for the system are
handled differently in the tests by REQ/REQva calls and are
distinguished in the test report.

Another example of requirements for the application can be found here
http://template2code.sourceforge.net/t2c-doc/cs.markup.html#cs.markup.g_array_sort

Also, it is important that requirement for a parameter really contains a restriction
on this parameter. E.g., there seems to be no such restriction in the
text "Minimum avail frames to consider PCM ready" (currently marked up
as snd_pcm_sw_params_set_avail_min.04). Any positive number may
represent such parameter. So this fragment of the spec probably
contains no requirements and it is not necessary to mark it up.

It is implicitly assumed that a function should work correctly with
the objects which it accepts as parameters, so it is not necessary to
provide an additional requirement for that.

However, some parameters may be intended to hold a value returned by
the function (out-parameters). E.g., "ctlp: Returned CTL handle"
(snd_ctl_open.02). The requirements for such parameters should be
marked as usual (requirements for the system under test, i.e., for the
function), because it is responsibility of the function to ensure the
parameter contains the correct value after the function returns.

3. Sometimes a requirement is formulated in different parts of the
description of a function, usually with different level of detail.
Consider, for example,

"Get card name from a CTL card info." (snd_ctl_card_info_get_name.01)
and
"Returns: card name" (snd_ctl_card_info_get_name.03).

These text chunks both formulate the
same requirement that the function returns the name of CTL card. To
point out that requirement is the same, you can do the following.

The most detailed text fragment (the first one in our case) is marked
up as usual - snd_ctl_card_info_get_name.01. The remaining fragment
(or fragments) is also marked up and assigned the same id, but with
leading "&": &snd_ctl_card_info_get_name.01.

More about using "&" may be found here
http://template2code.sourceforge.net/t2c-doc/cs.markup.html#cs.markup.g_array_new

4. The purpose of markup is to link the requirements to the
corresponding text fragments. So, the textual representation of a
requirement should not refer to a requirement, formulated in the
another text fragment. Consider the following fragment:

"dir: Sub unit direction" (snd_pcm_hw_params_set_rate_near.05) 

The fragment states nothing about the interpretation of the 'dir'
parameter. So if the textual representation of the requirement is
entered manually during markup, it better should not contain this
interpretation too.

Example of correct markup is in file
group___p_c_m___h_w___params_correct.html (it is attached).

This example markup contains several special features to be mentioned:

1) Usage of a "parent" requirement to group several related
requirements together. In this markup, the parent requirement is
snd_pcm_hw_params_set_rate_near.05, it groups snd_pcm_hw_params_set_rate_near.05.01,
snd_pcm_hw_params_set_rate_near.05.02 and snd_pcm_hw_params_set_rate_near.05.03 requirements.

In addition to such grouping, the text of the parent requirement
automatically refers to all child requirements.

A parent requirement is considered checked if and only if all its
child requirements are checked. So, the parent requirements need not
to be tested explicitly.

More about parent requirements -
http://template2code.sourceforge.net/t2c-doc/cs.markup.html#cs.markup.g_array_free

2) Group the text fragments that refer to the same requirement. This
grouping is based on using "&" sign in the IDs (see also note 3).

The same markup problem takes place for snd_pcm_hw_params_set_period_size_near() function.

5. There following construct often occurs in the descriptions of the return values:

"Returns: 0 otherwise a negative error code."

There are two elementary ('atomic') requirements in this text fragment: 

"The function shall return 0 on success" and
"The function shall return a negative number for an error code".

Correspondingly, this fragment should be marked up as containing a
parent and two child requirements, rather than a single requirement:

- "Returns" - func_name.05
- "0" - func_name.05.01 with the textual representation "The function
shall return 0 on success",
- "otherwise a negative error code" - func_name.05.02 with the textual
representation "The function shall return a negative number for an error code".


Regards,

Andrey

-- 
Andrey Tsyvarev
 
 Linux Verification Center, ISPRAS
 web:    http://www.linuxtesting.org
 e-mail: tsyvarev at ispras.ru

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.linux-foundation.org/pipermail/lsb-infrastructure/attachments/20100127/a4bd7b21/attachment-0001.html