Lack of Documentation

[roblabla]

Hello, I've been trying to use msgpack-java for a project of mine, and I keep having to look at the source code and trace through methods to try and understand how things work together. The main problem is that almost nothing outside of the main MessagePack class is documented.

Let's take a concrete example : I wanted to implement my own serializer for a certain type. I figured I would need to subclass Template after a while. However, I quickly hit this problem : What does the parametrized argument in read method of Template actually do ?

It took me a while to figure out it was to use with Unpacker.read(T to) . Had it been documented as such with javadoc, I wouldn't have had to fiddle for so long.

Another question : what is the difference between the annotations Message and MessagePackMessage ? What do the annotations Beans, Delegate, OrdinalEnum and their respective MessagePack* do ?

I hope those questions can be answered, and hopefully their docs will be integrated into the javadoc.

[oza]

Thank you for your comment, @roblabla. I'll blog the internal of msgpack-java in a few days to make it easier to understand msgpack-java. After reviewing from commiters of the blog, we should document it on javadoc and msgpack-wiki as you mentioned. Your contributing of docs by pull req is also welcome, of course :-)

Another question : what is the difference between the annotations Message and MessagePackMessage ? What do the annotations Beans, Delegate, OrdinalEnum and their respective MessagePack* do ?

@muga, can you describe this? I've not read annotation-related code, so I need your help.

[mikolak-net]

i'd like to voice my support for this issue. It's nice that msgpack has gotten a site overhaul, but that arguably left the documentation for Java (and Scala) in a worse state it was before. I'm glad the msgpack devs recognize the need for an update of the Javadocs and the Wiki .

[oza]

@mikkoz, thanks for your feedback. I'll share the state of lacks of documantation with developers at the hackathon. I'll also update Wiki/Javadocs at that time. If you have any idea about the information we should summarize about msgpack, let me know.

[mikolak-net]

@oza : Heh, I'd hate to hijack @roblabla 's issue, so I hope he agrees with what I'm about to write ;).

In my opinion, this should be included:

1. Javadoc:
   • all annotations
   • all interfaces (including, but not limited to, Template, TemplateBuilder, Packer, Unpacker, Value, MessagePackable, etc.)
   • all "entry" classes, such as MessagePack,
   • standard implementation classes, ones you would expect to occur in stacktraces often, such as AnyTemplate .
2. Wiki:
   • description of various annotations,
   • examples (with diagrams if possible) how pack/unpack of MessagePack works in Java.
3. "Java" tab on the main page:
   • basic pack/unpack code.
   • link to Quick Start in the Wiki.

Have fun on the hackathon!

[roblabla]

I don't mind at all, and it barely is a hijack considering the fact it is 100% on topic :) And that seems like an accurate list of what needs to be documented.

mikkoz notifications@github.com wrote:

Heh, I'd hate to hijack @roblabla 's issue, so I hope he agrees with what I'm about to write ;).

In my opinion, this should be included:

1. Javadoc:
   • all annotations
2. all interfaces (including, but not limited to, Template, TemplateBuilder, Packer, Unpacker, Value, MessagePackable, etc.)
   • all "entry" classes, such as MessagePack,
3. standard implementation classes, ones you would expect to occur in stacktraces often, such as AnyTemplate .
4. Wiki:
   • description of various annotations,
5. examples (with diagrams if possible) how pack/unpack of MessagePack works in Java.
6. "Java" tab on the main page:
   • basic pack/unpack code.
   • link to Quick Start in the Wiki.

Have fun on the hackathon!

---

Reply to this email directly or view it on GitHub: https://github.com/msgpack/msgpack-java/issues/40#issuecomment-22757686

Sent from my Android phone with K-9 Mail. Please excuse my brevity.

[oza]

@mikkoz, @roblabla, Thanks for your great feedback :-) I've split this issue based on your comments. I'll do this step by step, incrementally. If you can help us, it's very wonderful.

[mikolak-net]

@oza : I've noticed, great to see that :). If you need any further feedback, please let me know.

[oza]

@mikkoz OK, I'll notify you when I finish writing docs. Thank you :)

[chrislovecnm]

Thanks for the project, but I am looking for more documentation for handling beans with message pack. I would like to have a bean converted into a map based on parameter name rather than position of the field in the java file (very brittle);

Thanks in advance!