ktoso / protodoc-scala Goto Github PK

It's like JavaDoc, but for Google Protocol Buffers!

Java 2.41% Shell 0.49% Scala 97.10%

protodoc-scala's Introduction

ProtoDoc - It's like JavaDoc, but for Google Protocol Buffers

Have you ever worked with a BIG Protocol Buffers based application? It would be awesome if it had some kind of tool like JavaDoc, to always know what each field exactly means, even without having the proto file at hand right now.

Oh, wait. That's excatly what ProtoDoc is! ProtoDoc is a tool very much like JavaDoc, which scans your proto files and generates an easily searchable and most informative website with all information about yout ProtoMessages.

It's currently not production ready, and allows only for basic Messages to be parsed. But it should most probably be finished and fully working quite soon.

Live Demo

There is a live demo available here.

Coding notes

ProtoDoc is build by SBT so if you want to help out hacking, first download Scala 2.8.1 and sbt :-)

Output screenshots

ProtoDoc takes this:

package pl.project13;

/**
 * This is a simple Message which has some Inner Message defined.
 * Also, note that it has a default value on the name property.
 */
message MessageWithInner {
    /**
     * A number is just a simple property
     */
    required int32 number = 1;

    /**
     * This can be a name of your likeing, the default value is "lorem ipsum" etc
     */
    required string name = 2 [default = "loremipsum"];


    /**
     * Whoa, this is a comment on an inner message!
     * ProtoDoc is so cool!
     */
    message InnerMessage {

        /**
         * This is a comment on an inner messages field, cool~<br/>
         * <br/>
         * You may use it like this in your generated Java code:
         * <pre><code> setName("StringMyName");</code></pre>
         */
        optional string name = 3;
    }
}

and generates this:

Hooray!

protodoc-scala's People

Contributors

Stargazers

Watchers

Forkers

feijosamba

protodoc-scala's Issues

Support "import"

Allow importing of other proto files:

File A.proto

message A {}

File B.proto

import "A.proto";

message B {
  required A field = 1;
}

message Msg {

  optional Dwa field = 1;

  enum Dwa {
    ONE = 1;
  }
}

Add Verifier (Parse all files -> Verify -> Build site)

Another step is needed to examine cross references among files.

jeden.proto

package jeden;

message Jeden {
  optional Dwa dwa = 1;
}

dwa.proto

package b;

Allow enums to be used as field types, and validate them

This should be valid:

message A {
   enum Enum {}
   required Enum enumeration = 1;
}

while this should throw "type not found":

message A {
   enum Enum {}
   required MyUnknownEnum enumeration = 1;
}

Support multiple files

And in them, it should be possible to cross refer multiple field types (an Message in A.proto can use a Message in B.proto)

Support "option"

Such as in:

package pl.project13;

option java_package = "pl.project13.protodoc";

message Msg {}

Allow messages to be used as field types

This is currently implemented for enums, it's really easy to do the same for messages.

message A { 
  message Inner {}
  required Inner field = 1;
}

Support "extensions"

allos messages to declare extension spaces
allow messages to add extensions