myfaces-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Gerhard Petracek" <gerhard.petra...@gmail.com>
Subject Re: JavaDoc and checkstyle
Date Tue, 09 Dec 2008 18:43:50 GMT
hi,

that's right - since it was a pretty long thread which also includes other
topics, i just linked the first message as a starting point.
anyway, does someone know a nice and correct wiki about such topics? so we
could link it in our wiki.

regards,
gerhard



2008/12/9 Simon Lessard <simon.lessard.3@gmail.com>

> Hi Simon,
>
> Gerhard link is correct although not including the whole post, one of the
> reply from Matthias. Maybe we should raise the issue on legal-discuss? At
> worst, your way of writing the doc sounds very reasonable as well. My team
> wouldn't need the go away for a while part however since it's two completely
> different persons coding and documenting for code reviews purpose.
>
>
> Regards,
>
> ~ Simon
>
>
> On Tue, Dec 9, 2008 at 12:23 PM, Simon Kitching <skitching@apache.org>wrote:
>
>> Hi,
>>
>> I doubt very much that simply retyping javadoc from the spec is legally
>> sufficient to permit non-Aapache-licensed text to be included in an
>> Apache-licensed file.
>>
>> Note that I was *asking* whether copying was allowed; hopefully there is
>> something in the spec licenses that *does* permit it. But if not, then
>> we must follow the relevant copyright laws. I definitely interpreted the
>> original JSF1.1/JSF1.2 specs as NOT permitting copying of javadoc from
>> the spec into our classes.
>>
>> Do you happen to have a link (or even the email subject line) for the
>> earlier discussion? I must have missed that...
>>
>> Note that for dtd and schema files it is pretty easy to avoid copyright
>> issues; the vast majority of such files is data-structure definition
>> that has only one possible form, and therefore is not copyrightable.
>> Simply taking someone else's file is still wrong here, but the original
>> can be used as a "reference" for the non-copyrightable technical
>> details, so creating the new version is effectively pretty close to
>> "just retyping".
>>
>> Javadoc, however, is prose writing which is creative expression. So it
>> should *not* be used as a reference when writing new javadoc; that would
>> be plagiarism.
>>
>> I did create a significant amount of javadoc for the JSF1.1 and JSF1.2
>> implementations (though still far from complete coverage); my approach
>> was to
>> (a) ensure that the implementation matched the specification description
>> (referencing the original docs)
>> (b) go away for a while
>> (c) some time later, write the javadoc based on the *code* (not using
>> the original docs as a reference)
>>
>> From your other email:
>> <quote>
>> p.s. I know that 1.1 and 1.2 don't have any JavaDoc copied, actually it
>> only refer to the official one online which isn't very useful for
>> offline users nor those working directly looking at the code. Keeping
>> JavaDoc out is of course a valid option as well if the community wishes
>> it, but it also implies our Maven generated JavaDoc for the site won't
>> be any good.
>> </quote>
>>
>> I think the javadoc that was specifically written for myfaces classes is
>> more useful for end-users than the spec stuff (more helpful, less picky
>> technical detail). But yes it is a minority of classes, with most still
>> just linking to the external specs. I'm sure nobody *wants* to keep
>> javadoc external to the classes, but recreating all the docs is a big
>> task, and the alternative (copying) was IMO just not legal.
>>
>> Yes, it's annoying but copyright is copyright. And if we don't follow
>> the law then the spec copyright-holder has every right to sue.
>>
>> IANAL and all that.
>>
>> Regards,
>> Simon K.
>>
>> Simon Lessard schrieb:
>> > Hi Simon K.,
>> >
>> > We had that discussion not long ago on another post. We're actually
>> > retyping the whole thing, but mimicking the official JavaDoc. Since
>> > it's not copied directly it seems it's allowed.
>> >
>> > ~ Simon
>> >
>> > On Tue, Dec 9, 2008 at 10:06 AM, Simon Kitching <skitching@apache.org
>> > <mailto:skitching@apache.org>> wrote:
>> >
>> >     Hmm..by the way, are you copying-and-pasting the JSF javadoc into
>> >     myfaces classes? If so, are you sure that this is allowed? Javadoc
>> >     descriptions would definitely be copyrightable, so explicit
>> permission
>> >     would be needed to place text released under the CDDL into a file
>> >     licensed under the Apache license...
>> >
>> >     In Myfaces core 1.1 and 1.2 releases we have been careful to NOT
>> copy
>> >     any javadoc from the spec..
>> >
>> >     Regards,
>> >     Simon
>> >
>> >     >> Simon Lessard wrote:
>> >     >>
>> >     >>> To be more precise checkstyle whines about missing @param and
>> >     @return,
>> >     >>> which
>> >     >>> is theoretically nice. However, JSF's JavaDoc is broken and
>> >     doesn't
>> >     >>> specifies those most of the time, so the question is is it
>> >     better to match
>> >     >>> the official API or to make checkstyle happy?
>> >     >>>
>> >     >>> On Tue, Dec 2, 2008 at 6:33 PM, Simon Lessard
>> >     >>> <simon.lessard.3@gmail.com
>> >     <mailto:simon.lessard.3@gmail.com>>wrote:
>> >     >>>
>> >     >>>
>> >     >>>> Hi all,
>> >     >>>>
>> >     >>>> It seems that checkstyle doesn't like JSF's official JavaDoc.
>> >     Personally
>> >     >>>> I
>> >     >>>> would give higher priority to completed comments than
>> >     checkstyle whining,
>> >     >>>> what you guys think about it?
>> >     >>>>
>> >     >>>>
>> >
>> >
>>
>>
>


-- 

http://www.irian.at

Your JSF powerhouse -
JSF Consulting, Development and
Courses in English and German

Professional Support for Apache MyFaces

Mime
View raw message