Name: dgC58589			Date: 01/07/98


(See http://www.javasoft.com/products/jdk/1.2/docs/api/java.lang.Throwable.html#fillInStackTrace() .)

The documentation for java.lang.Throwable.fillInStackTrace
is not clear.  It is not apparent what the method
is good for, or exactly what difference it makes.

There is an example, but it is not a good one--
it's not a case where calling fillInStackTrace 
makes much difference.  (Well, maybe the line
number changes, but the chain of called method
names does not.)


The text should mention that:
- the stack trace is already filled in when the 
    exception is constructed, from the stack at 
    the point of the creation of the exception
    object (to help indicate that fillInStackTrace
    is needed only for changing this default)
- fillInStackTrace updates (replaces) the existing
    stack trace in the exception with the stack 
    trace from the point of the call to 
    fillInStackTrace

The example should show an exception originally
generated in a called function (so that calling
fillInStackTrace makes a noticeable difference 
(cutting off the chain of called methods)).

Text should point out that calling fillInStackTrace
is useful for suppressing some details of the call
stack for exceptions created in deeper-nested
method calls.  (Or for updating in a stack trace
for an exception creating at a higher level and
passed in, which would, of course, be a really
weird use.)
(Review ID: 22685)
======================================================================