Skip to content

Lack of Documentation #40

Open
Open

Description

@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.

Activity

  1. oza commented on Aug 15, 2013

    @oza
    Member

    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.

  2. mikolak-net commented on Aug 15, 2013

    @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 .

  3. oza commented on Aug 16, 2013

    @oza
    Member

    @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.

  4. mikolak-net commented on Aug 16, 2013

    @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!

  5. roblabla commented on Aug 16, 2013

    @roblabla
    Author

    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:
    #40 (comment)

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

  6. oza commented on Aug 28, 2013

    @oza
    Member

    @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.

  7. mikolak-net commented on Aug 28, 2013

    @mikolak-net

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

  8. oza commented on Aug 28, 2013

    @oza
    Member

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

  9. chrislovecnm commented on Jul 30, 2014

    @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!

  10. added this to the v07 milestone on Jun 23, 2015
  11. modified the milestones: v07, v08 on Jan 4, 2016
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions