Mark Webb-4 wrote: > > I really do not think the ByteBuffer javadoc for the trunk is all that > bad. > Could you please list some specific areas that would necessitate a > rewrite? >
Walking through the API methos in alphabetic order: 1) You should use allocateDirect() instead of allocate(int capacity, boolean direct) in order to stay in line with NIO's ByteBuffer 2) array(), arrayOffset(), asCharBuffer(), and many others are missing Javadoc. All they contain is a hyperlink back to NIO.ByteBuffer. You should either subclass ByteBuffer or use composition. If you go with composition you can remove all methods which already exist in ByteBuffer and just add a single getBuffer() method which returns the underlying buffer. Either case takes care of documentation and exposing all ByteBuffer-related functionality. 3) It isn't clear what happens if you wrap(ByteBuffer) and then expand(). What happens to the underlying ByteBuffer? :) 4) I would eliminate fill(int), fillAndReset(int) or rename them to clear(int), clearAndReset(). Consider the cost/benefit of adding convinience methods for a special value of zero. I would just force the user to pass in the zero in favor of dropping two methods. Also the fact that fill(byte, int) takes two numbers in a row is dangerous; the user should ideally get a compiler error if he passes in the arguments in the wrong order. 5) getAllocator() is confusing because it is static. Perhaps you meant to call it getDefaultAllocator()? 6) getHexDump() doesn't mention any side-effects. Does it modify the buffer position()? 7) getString(CharsetDecoder) is questionable since CharsetDecoder.decode(ByteBuffer) already exists 8) getUnsigned() should be renamed to getUnsignedShort() keeping in line with getUnsignedInt(). 9) mark(), limit() are also questionable. They should be hidden inside the InputStream view of the ByteBuffer, not exposed on its main API. 10) prefixedDataAvailable()'s Javadoc reads "Returns true if this buffer contains a data which has a data length as a prefix and the buffer has remaining data as enough as specified in the data length field". I don't know about you, but I have no clue what that means :) Either there is a typo or something is wrong with the sentence structure, either way I don't understand sorry :( 11) putChar() and all String related operations are already provided by ByteBuffer.asCharBuffer()'s API. 12) It isn't exactly clear how getObject(), putObject() works. Does the Object have to be Serializable? 13) Sweep()'s Javadoc talks about clearing the buffer, perhaps this method should be renamed to clear()? 14) It isn't clear what ByteBuffer.toString() does. The Javadoc is empty. There are many more small nuances but those are the major ones that come to mind right now. On a related note, if any of you haven't seen this video yet, I *highly* recommend it: http://www.infoq.com/presentations/effective-api-design It is an hour long, but it is worth every second of your time! Gili -- View this message in context: http://www.nabble.com/Refactor-ByteBuffer-for-2.0--tf4042211.html#a11486146 Sent from the mina dev mailing list archive at Nabble.com.
