[protobuf] protoc plugin compiler extension framework
Is it possible, with the plugin framework, to add certain annotations or even comments (like javadocs) to the .proto file that make it all the way through to the generated java code? -- You received this message because you are subscribed to the Google Groups Protocol Buffers group. To post to this group, send email to proto...@googlegroups.com. To unsubscribe from this group, send email to protobuf+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/protobuf?hl=en.
[protobuf] Re: protoc plugin compiler extension framework
Yeah, I agree with it being cluttered if they were handled as
options. I'm still trying to wrap my mind around the plug-ins and
whether or not they are useful to my project.
If the development team would actually consider something to propagate
generated code documentation, one thing to consider for non-java
lanauges is doxygen. Doxygen comments look a lot like javadoc
comments, and there is support for C, C++, Objective-C, Python,
Fortran, C#, and a bunch of others.
I wouldn't use Doxygen for Java, of course. (What would be the
point?)
C# is a little tricky, in that Microsoft defines an XML
Documentation language but only gives you Sandcastle (unsupported,
complicated) to do anything useful with them.
On Dec 22, 1:28 pm, Kenton Varda ken...@google.com wrote:
The plugin framework is not meant for this. Plugins can only insert code at
points that have explicitly been declared by the original generator. For
example, in Java, the code generator generates one insertion point in each
class. So, you can add new methods to a message type, but you cannot stick
javadoc comments on the existing methods.
I think that a system which let you arbitrarily edit the generated code
would be too fragile -- any change to the code generator would potentially
break plugins. In fact, I'm even worried that the current system is risky
because it allows plugins to get access to private members which could
change, but I don't see any way around that.
All this said, I think it would be great if the protocol compiler supported
some format for documentation comments and automatically copied those
comments into the generated code. But no one has actually worked on this
yet.
On Tue, Dec 22, 2009 at 6:42 AM, Christopher Piggott
cpigg...@gmail.comwrote:
Hmm maybe I can use the UninterpretedOption message to do this.
Would something like this work?
message ChrisMessage {
option javadoc = This is an object representing Chris's Message;
repeated int32 field1 = 1 [javadoc=This is a javadoc for field 1];
repeated int32 field2 = 2 [javadoc=This is a javadoc for field 2];
}
Then write a plug-in that finds those and writes the ones whose
NamePart.equals(javadoc) in as a /** comment */
Possible?
--
You received this message because you are subscribed to the Google Groups
Protocol Buffers group.
To post to this group, send email to proto...@googlegroups.com.
To unsubscribe from this group, send email to
protobuf+unsubscr...@googlegroups.comprotobuf%2bunsubscr...@googlegroups.com
.
For more options, visit this group at
http://groups.google.com/group/protobuf?hl=en.
--
You received this message because you are subscribed to the Google Groups
Protocol Buffers group.
To post to this group, send email to proto...@googlegroups.com.
To unsubscribe from this group, send email to
protobuf+unsubscr...@googlegroups.com.
For more options, visit this group at
http://groups.google.com/group/protobuf?hl=en.
[protobuf] Re: Thinking of implementing: extract documentation in .proto file and store in FileDescriptorProto
On Dec 22, 4:53 pm, Henner Zeller henner.zel...@googlemail.com
wrote:
/*
* some block comment
*/
int32 some_field = 1;
int32 some_other_field = 2; // short comment.
I would be fine with that, but I also woudn't have a problem with you
requiring everything be a block, because you can still do it on one
line:
/**
* some block comment
*/
int32 some_field = 1;
int32 some_other_field = 2; /** short comment */
Notice I did keep the /** in there, because:
Is this a constraint we want to have or need
I think so. I think it's helpful to say This comment is special. I
can see a good argument, though, that it's redundant - especially if
pass documentation comments to generated code is a .proto file
option. I like /** something */ because it fits well with java and
C/C++ (with Doxygen) and because I think the Python triple-quote is
ugly. If you really wanted // then I'd be happiest with ///
Ultimately, though, the .proto is its own language, so decide upon
whatever makes sense to you. It shouldn't be overly cumbersome or
ugly, and it should be reasonably easy for the .proto parsing code to
handle (so you don't wind up hating me).
The only requirement I'd propose is that there should be no empty line
between a block comment and the field/message it describes. This
enforces readability and prevents stray comments or file-header
comments being accidentally included in the documentation.
I agree.
There are some other things you didn't ask that are bothering me a
little. One has to do with fields. The fields themselves, at least
in java, are private, so documenting them in this way is not
especially useful. What you really want is to have these documents
put something meaningful in the .hasSomething(), .getSomething
(), .getSomethingCount(), etc. and in the builder, to .setSomething()
and .addSomething(), and similar methods.
How to make this work and look good is a real question in my mind.
If you do:
message Something {
required int32 ageField = 1; /** Age of this human */
}
what you really would want for useful inline documentation (using
javadoc as an exapmle, but same for Doxygen) would be something like
/** Get ageField
* @return Age of this human
*/
public int hasAgeField() { ... }
for the builder:
/** Set ageField
* @param value Age of this human
*/
public void setAgeField(int value) { ... }
and similar for lists etc. The ageField part I grabbed from the
field name, and the actual comment I applied to the @return and
@param.
I would have to take some time to think about how you would phrase
this so that it makes sense for lists.
This is kind of where I was going / what I was wishing for with regard
to fields. The decisions are a little more straight-forward when it's
documentation for messages, as that documentation I would expect to
more or less pass straight through unchanged, and use it to document
the classes being generated. (The fields are just more complicated,
since the actual fields in the class are private).
I'm not sure where you'd go with services - method calls I suppose,
but for java/doxygen those would be the form @param @param ...
@return. I don't really know python/php so I'm not sure how this maps
over to those languages.
Is that helpful?
--
You received this message because you are subscribed to the Google Groups
Protocol Buffers group.
To post to this group, send email to proto...@googlegroups.com.
To unsubscribe from this group, send email to
protobuf+unsubscr...@googlegroups.com.
For more options, visit this group at
http://groups.google.com/group/protobuf?hl=en.
[protobuf] Re: Thinking of implementing: extract documentation in .proto file and store in FileDescriptorProto
But more difficult is comments like this: // Blah blah blah here is a list: // * blah blah blah // * blah blah blah blah // * blah blah Hmm. Javadoc would let you encode lists as ul li ... li ... / ul which would be nice, though I suppose not critical. Seems that you could just pass the html through, though. Garbage in, garbage out ;) So you would get a multi-line comment with a different number of whitespaces in front of each line (maybe with the common number of whitespaces (i.e. one) removed from all of them, as suggested above). Yeah. Not to repeat my other message, but @param @return etc. are important things for the accessors/setters/etc. Otherwise this won't be able to generate documentation that IDEs will find useful. Documenting private fields is of limited use, IMO. and in a lot of cases aren't even translated to the final documentation. -- You received this message because you are subscribed to the Google Groups Protocol Buffers group. To post to this group, send email to proto...@googlegroups.com. To unsubscribe from this group, send email to protobuf+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/protobuf?hl=en.
Re: Save multiple messages to a single file C++
This whole topic - how to save multiple messages to a single stream - comes up frequently enough that I'm starting to think there should be a more flexible answer than what's in the FAQ. Declaring a one-byte End of Object seems like it would be one way to handle it. Whatever it is, it should keep in mind that protocol buffers may not be coming from files, but streaming from sockets (e.g. tcp). If nothing else, I think this should be addressed for the sake of consistency. I've been encoding a 32-bit length before my my protocol buffers... which works just fine but like I said, consistency would be helpful. Just my $0.02. --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups Protocol Buffers group. To post to this group, send email to protobuf@googlegroups.com To unsubscribe from this group, send email to protobuf+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/protobuf?hl=en -~--~~~~--~~--~--~---
Re: Warnings compiling MessageLite.java in protobuf-2.2.0
I should have been more specific about what compiler I'm using: open- jdk-6 version 6b14-1.4.1, on a linux (ubuntu) development environment from within netbeans. --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups Protocol Buffers group. To post to this group, send email to protobuf@googlegroups.com To unsubscribe from this group, send email to protobuf+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/protobuf?hl=en -~--~~~~--~~--~--~---
open jdk
I have been having a lot of problems getting things to compile - the java protobuf library, to begin with; and even after getting that to compile, I couldn't get MyProtos.java (generated code) to compile. Come to find out, if I switch to sun-jdk-6 everything builds. Is this a known issue, or is it something with my particular compiler setup? --~--~-~--~~~---~--~~ You received this message because you are subscribed to the Google Groups Protocol Buffers group. To post to this group, send email to protobuf@googlegroups.com To unsubscribe from this group, send email to protobuf+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/protobuf?hl=en -~--~~~~--~~--~--~---
