[OASIS Issue Tracker] (VIRTIO-63) Examples (76+)

[OASIS Issues Tracker <workgroup_mailer@lists.oasis-open.org>]

     [ https://tools.oasis-open.org/issues/browse/VIRTIO-63?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Michael Tsirkin updated VIRTIO-63:
----------------------------------

    Resolution: 

accepted on 2014-03-11
applied in commit r322

> Examples (76+)
> --------------
>
>                 Key: VIRTIO-63
>                 URL: https://tools.oasis-open.org/issues/browse/VIRTIO-63
>             Project: OASIS Virtual I/O Device (VIRTIO) TC
>          Issue Type: Bug
>         Environment: Normative
>            Reporter: Patrick Durusau
>            Assignee: Rusty Russell
>
> 2 Basic Facilities of a Virtio Device reads in part:
> *****
> To reinforce this the examples use typenames like "le16" instead of "uint16_t".
> *****
> I don't think this is part of the "normative" part of the specification. The "normative" portion of a specification consists of the statements and rules that an implementer follows in order to conform to the specification.
> This statement doesn't look "normative" to me.
> If it was intended as an aid to the reader, not something they follow but something helpful to know, then it should be a note. Which is formatted in such a way to separate it from the normative text. So that when you reference a section as part of a conformance clause statement, everyone knows what part of it is to be followed and which parts not.
> For example, you could say under section 1, that all notes in the specification are non-normative. That keeps you from having to mark every example as non-normative. They still need distinct formatting but that is a separate issue.
> By my count, you use example/examples some 17 times so at a minimum, all of those should be extracted and written as notes. 
> I am assuming that under 2.3 Configuration Space, the grayed material that begins: u32 before, after is also an example? I could some 59 of those in the specification. 
> BTW, all examples should be numbered serially in the specification. It facilitates references to examples by the specification and other texts. 



--
This message was sent by Atlassian JIRA
(v6.1.1#6155)