Every generated file should include a URL for more information

google / auto

A collection of source code generators for Java.

Apache License 2.0

10.43k stars 1.2k forks source link

Every generated file should include a URL for more information #291

Open kevinb9n opened 8 years ago

kevinb9n commented 8 years ago

It's important that anyone who comes across any generated file should be able to understand where it came from. imho, that means a URL reference.

For an AutoValue generated implementation, the URL should be https://github.com/google/auto/tree/master/value.
For a class generated by an AutoValue extension, the extension author should be compelled to supply this URL
(others can comment re: AutoFactory and others)

Open questions:

Should this URL simply be the content of @Generated? I think it should, and the current qualified class name we spit out is fairly useless. The fact that the @Generated annotation javadoc recommends FQCN as a convention matters basically not at all to me. The alternative is that we put this in a comment, which might as well be a javadoc comment (not that it seems remotely likely someone would be looking at generated javadoc for a generated class, but why not?)
If the generators can even spit out a version-specific URL that seems even cooler....

kevinb9n commented 8 years ago

@rharter to consider the extension-specific part of this.

rharter commented 8 years ago

I think this is a good idea. Regarding extensions, since the extensions generate the file and AutoValue doesn't really know about or touch the contents of it I think the best we can do is make adding a url to the content of @Generated a convention, as opposed to enforcing it in any way. Do you think adding it to the documentation around creating extensions (which we should probably create?) is enough?

eamonnmcmanus commented 8 years ago

There is a convention for the value of @Generated and it is not URLs. That might not matter at all to Kevin but it makes me a little bit sad to flout it. I notice though that the value member is actually a String[] so perhaps we could have [0] be the FQCN and [1] be the URL. There's also a comments member which could house the URL.

kevinb9n commented 8 years ago

It just seems like a worthless convention to me. It's annoying to find a class name and still know nothing about where that class even came from or how to find it.

On Mon, Nov 23, 2015 at 5:19 PM, Éamonn McManus notifications@github.com wrote:

There is a convention for the value of @Generated and it is not URLs. That might not matter at all to Kevin but it makes me a little bit sad to flout it. I notice though that the value member is actually a String[] so perhaps we could have [0] be the FQCN and [1] be the URL. There's also a comments member which could house the URL.

— Reply to this email directly or view it on GitHub https://github.com/google/auto/issues/291#issuecomment-159120629.

Kevin Bourrillion | Java Librarian | Google, Inc. | kevinb@google.com

JakeWharton commented 8 years ago

I too generally agree with the worthlessness of the value member. Sadly its Javadoc is unusually harsh saying "MUST have the name of the code generator".

Another knock against @Generated would be that it's omitted in its entirety when the target classpath (aka Android runtime) does not contain the class (see GeneratedDoesNotExistTest.java).

rharter commented 8 years ago

Perhaps, in light of the convention and Javadoc around @Generated it makes sense to make the convention a link in the Javadocs of the generated classes, which would also fit the normal java conventions better.

ronshapiro commented 5 years ago

ErrorProne sometimes uses the value property.

Dagger uses the comment attribute FWIW

kluever commented 5 years ago

This seems easy enough and is probably worth doing.