ByteBlockPool's documentation is completely useless [LUCENE-5613]

[asfimport]

This is a nice reusable component yet the documentation for it is completely useless. There are also API elements that seem to be remnants of an ancient past.

Can we clean it up for 5.x?

---

Migrated from LUCENE-5613 by Dawid Weiss (@dweiss)

[asfimport]

Dawid Weiss (@dweiss) (migrated from JIRA)

For example is allocSlice really needed there? Seems like only TermsHashPerField and ByteSliceWriter are using it (and the latter is not used anywhere).

[asfimport]

Robert Muir (@rmuir) (migrated from JIRA)

IMO the class is internal enough we should definitely clean up it for 4.x too.

[asfimport]

Robert Muir (@rmuir) (migrated from JIRA)

Also for the record, its always sad to see this:

  // Fill in a BytesRef from term's length & bytes encoded in
  // byte block
  public void setBytesRef(BytesRef term, int textStart) {

This is a public method in a public class, so using a javadoc-style comment goes a long way :)

[asfimport]

Michael McCandless (@mikemccand) (migrated from JIRA)

Big +1 to clean this up, and if we can move the hairy allocSlice stuff out we should.