I had occasion to read most of the JVMTI doc closely this week, and I came
up with the following list of mistakes, typos, etc. I marked up almost all
of it, but not as much in the object, thread, and monitor sections.

Except for the first one, which is related to some boilerplate text in the
XML formatter, the items are in top-to-bottom order in the document. The
only significant one is about Get Stack Trace and friends. The rest don't
really prevent understanding, but fixing them will give us a more
professional document.

* Boilerplate code in the XML formatter:

The text in the Callback Safe section for Allocate and other safe
functions has the word "handles" where it should be "handlers."

* Section "JAVA_TOOL_OPTIONS"

The first sentence starts with "Since" but the sentence ends early.
Replace period with comma, or remove "Since."

* Section "Environments"

There is an anchor with a misspelling in it: the actual anchor name in the
document is "jvmtiEnvAcess" (note just one 'c') but there is a (broken)
reference to it using the seemingly-correct spelling "jvmtiEnvAccess" in
the Environments section.

* Section "Bytecode Instrumentation"

The phrase "This approach also provides complete control to the agent"
should end with a colon, not a comma. If some documentation style person
has said you can't use colons, then rephrase this sentence - add "because"
or "for example" or something.

* Section "Functions > Accessing Functions"

The sentence "GetEnv will return JNI_EVERSION if a compatible version is
not available, if JVM TI is not supposed or JVM TI is not supported in the
current VM configuration." has the word "supposed" instead of "supported."

* Deallocate

The description of the "mem" parameter contains this: "On return, the
elements are set." That is wrong; it should say "On return, the memory is
deallocated (freed)."

* Get Thread State

The "body text" parts of this section (and only this section) do not
word-wrap properly. It wraps to the width of a nearby table, not to the
right edge of the browser window like most body paragraphs. All other
sections appear to be formatted correctly, even if they have tables which
are wider than the browser window.

* Suspend Thread List

The sentence "Threads that are currently suspended are not suspended"
makes no sense. Do you mean they are not suspended *again*? I'd say
"Threads that are currently suspended do not change state."

* Get Thread Info

Description of info_ptr contains this sentence: "For JDK 1.1
implementations that don't recognize context class loaders, the
context_class_loader field will be NULL." Since this spec applies to 1.5
and above, this is unnecessary.

* Run Agent Thread

The description contains the following sentence: "Ideally, all calls to
Java programming language code should be done during the callback for the
VMInit event to avoid any interaction with the target application." I
don't think this is a valuable warning for an agent writer. Of course any
call from the agent to Java will perturb the target program, but why say
so here?

Also: in the sentence "The following thread priorities are useful" I think
you mean "usable" or "can be used."

* Get Stack Trace

The terms "deep," "deeper," and "deepest" are used inconsistently in this
function, and in the related functions "Get All Stack Traces" and "Get
Thread List Stack Traces." Also, the term "oldest" is used, which means
the same as what "deepest" is supposed to mean.

Correct usage of "deepest" is "farthest from the top of the stack." The
"deepest" frame is at the "bottom" of the stack, and is the oldest frame -
the first frame ever pushed.

The place where "deepest" is used this way (correctly) is, "there may be
frames deeper than main() and run()."

But before that, the description says "the max_frame_count deepest frames
are returned." This is wrong. The *shallowest* (newest, nearest the stop
of the stack, most recent) frames are returned. The next sentence says
"Deepest frames are at the beginning of the returned buffer" but again,
this should be *shallowest*.

The sentence about the example says it "causes up to five of the deepest
frames to be returned" but again, it should say the *shallowest.*

Another way to think about the correct meaning of "deeper" is "larger
values for stack_depth" ... a depth value of 10 is "deeper" than a value
of 3, and represents going to older frames.

Please note that this is not just a matter of preference or culture
("stacks grow up" vs. "stacks grow down"): when talking about a stack,
the "top" of the stack is always the most-recently-pushed frame, the
"bottom" is the oldest frame, and the direction from top to bottom is
"deeper."

* Get All Stack Traces

See "Get Stack Trace" regarding "deep" and "shallow."

Also: this sentence has a bug: "All stacks are collected simultaneously,
that is, no changes will occur to the thread state or stacks between the
sampling one thread and the next." The word "of" is missing between
"sampling" and "one."

* Get Thread List Stack Traces

See "Get Stack Trace" regarding "deep" and "shallow."

* Generate Events

The phrase "The history of what events have previous been sent" has a
typo: should be "previously."

In the sentence starting "This function is useful..." the comma should be
a colon. If somebody says you may never use a colon, then rephrase this
sentence.

* Capabilities section

In each case, phrases like "add (or relinquish) the capabilities pointed
to by capabilities_ptr" need to be modified. They should say "Add (or
relinquish) the capabilities whose values are set to '1' in
*capabilities_ptr."

* Native Method Bind event

The description ends like this: "Some events may be sent during the
primordial phase, JNI and most of JVM TI cannot be used at this time but
the method and address can be save for use later."

First, the first comma in that sentence should be a period or a semicolon.
Second, the word "save" should be "saved."

* Class Load Hook event

The text says "This event may be sent before the VM is initialized. During
this time no VM resources should be created." It would be nice to mention
that you *can* call Allocate.

Thanks.

-- Allan Pratt
Rational software division of IBM