[sv-ec] Feedback on 1356 (MI proposal)

In addition to the substantive issues that are being discussed, I have
a fairly long list of editorial and clarification changes needed in the
1356 proposal. Basically the entire proposal needs a very careful
editorial scrub. Here are the things I found:

1) 8.25 "An interface class shall contain only methods of pure virtual
type"
      should be "An interface class shall contain only pure virtual
methods".
2) 8.25 "A virtual class that is implementing an interface class is not
required
      to fully define the methods, however they must be fully defined by
descendent
      classes." This is attempting to re-express the rules regarding
abstract
      classes. Why is this even necessary? We should just state that
virtual classes
      inherit the "pure virtual" prototype and leave the rest to the
normal definitions.
3) 8.25 There are several parenthetical "(multiple)" uses. They are
superfluous
      and as we try to avoid parenthetical comments, I'd suggest just
removing them.
4) 8.25 "meaning that it implicitly specifies all the ..." This is
obviously still
      under discussion but the "implicitly specifies" here is not the
right way to
      express the behavior. It "inherits" the items or defines them.
"implicitly
      specifies" is inconsistent terminology.
5) 8.25 and throughout -- "implements" is a keyword and should be
bold/courier
      not italic.
6) 8.25 "task void put" and "task T get" -- tasks don't have return
types. Either
       make put a void function or a task with no return type. get
should be a
       function. Problem is throughout the example.
7) 8.25 In the "Fifo" class, the prototype for "put" is not a legal
override as the
      name of the formal does not match the PutImp prototype.
8) 8.25 We should make Fifo be legal by having at least a trivial body
for the
      put/get.
9) 8.25 "The Fifo class then uses the keyword implements to consume the
      prototypes of put and get..." What does "consume the prototypes"
mean?
      This should be reworded.
10) 8.25.1 Notes to the editor should be in green.
11) 8.25.2 "There is a difference between how classes, virtual classes, and
        interface classes inherit each other." This is a pretty awkward
sentence and
        should be clarified.
12) 8.25.2 "the implementing class shall supply a definition or an error
will be
        issued". Not necessarily -- if the implementing class is
abstract, it may not
        provide a definition, a subsequent concrete derivation may do so.
13) 8.25.2 "meaning that the sub interface class can have additional
methods
        outlined but may not define any of them." What does "outlined"
mean?
        Rephrase in terms of "providing additional prototypes" or similar.
14) 8.25.2 "A class can only implement..." Use "shall" here.
15) 8.25.2 Fifo has the same problems as noted in point (7) and should also
        have trivial bodies.
16) 8.25.2 "used in the implemented classes PutImp and GetImp." The font
        for PutImp and GetImp needs to be corrected.
17) 8.25.2 "type T_out = logic," logic should be bold
18) 8.25.2 Again, Fifo example has the same problems as in point (7)
19) 8.25.3 "within a interface class" the "a" should be "an"
20) 8.25.3 We are consistently trying to avoid the use of "foo" and "bar"
        in the LRM. Please rework the example to avoid that.
21) 8.25.3 "interfaceClassA #(type T1 = logic)" is missing a trailing ";"
22) 8.25.3 Be careful about linebreaks and comments. Keep comments
        short so that we avoid potential issues with final formatting
23) 8.25.3 "return type bit[1:0] agrees with" What does "agrees with" mean?
        Use match or equivalent as appropriate.
24) 8.25.3.1 "There is a restriction placed on what type is passed along
to the
        implementation of an Interface Class." This should be deleted.
25) 8.25.3.1 Change use of "foo" and "bar"
26) 8.25.4 "it shall be legal to assign an interface class handle to a
child
        object that implements it" This is incorrectly stated --
objects references
        are assigned to handles. Handles are not assigned to objects.
27) 8.25.4 "It shall also be possible to have multiple references..."
Just after
       this sentence, correct the indentation in the example.
28) 8.25.4 "$cast(get_ref, put_ref);" I don't think this ends up being legal
        based on the Mantis 3293 text. We'll either need to expand 3293
along
        with this proposal or state that such a "sideways" cast is illegal.
29) 8.25.4 "It shall also be legal to cast implemented objects onto their
        prototype interface class handles" Fix the font/alignment in
the example
        just after this sentence.
30) 8.25.4 "a variable of an interface class type shall not be
instantiated" I don't
        think this is really the right way to say this. "An object of
an interface class type
        shall not be constructed" might be better.
31) 8.25.5 "Any subsequent definition, or duplicate declaration of these
names
        must have exactly the same prototype" Avoid the term "exactly
the same".
        Use "compatible prototype" or similar.
32) 8.25.5 "It is an error to declare, define, or acquire" What does
"acquire" mean?
33) 8.25.5 In the example, rewrite to remove "foo" and "bar".
34) 8.25.5 In InterfaceExt definition, fix fonts and add "pure" to the
method.
35) 8.25.5 "It sees foo from the" the name "foo" should have the font
corrected.
        "sees" is a bit informal -- should use something like "Since foo
is visible.."
36) 8.25.5 Throughout the examples, check for correct "task" and "function"
        use and types.
37) 8.25.5 "bit and int respectively" The types bit and int should be
bold/courier.
38) 8.25.5 "not identical prototypes" Again, change this to
"compatible" or similar.
39) 8.25.5 "The same will occur" should be "It shall also be illegal..."
40) 8.25.5 "feeding the put method within it" What does "feeding" mean?
41) 8.25.5 "it will recognize the parameter difference" This is pretty
        informal wording.
42) 8.25.5 "virtual function function bit bar();" redundant
"function". Change
        "bar"
43) 8.25.6 "Because virtual classes do not have to fully define their
implementation,
        they are free to partially define their methods." This is
pretty awkward -- it
        reads like a circular definition. Something like "... some
methods may remain
        pure".

That's all for now.

Gord.

-- 
--------------------------------------------------------------------
Gordon Vreugdenhil                                503-685-0808
Model Technology (Mentor Graphics)                gordonv@model.com
-- 
This message has been scanned for viruses and
dangerous content by MailScanner, and is
believed to be clean.