Re: JavaDoc and checkstyle
I would also prefer to change the checkstyle rules to ignore missing @param and @return comments. Sometimes params really are obvious enough not to be documented, and in some other cases it is better to document them as part of the main method description rather than a separate tag. So blindly enforcing this check doesn't seem helpful... 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 [EMAIL PROTECTED]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? -- View this message in context: http://www.nabble.com/JavaDoc-and-checkstyle-tp20803530p20911066.html Sent from the My Faces - Dev mailing list archive at Nabble.com.
Re: JavaDoc and checkstyle
I wouldn't change the CheckStyle rules to ignore missing @params. Why? Because often you (well, probably not you, but someone else) changes a param name but forgets to change the corresponding JavaDoc. CheckStyle is a good way to warn you about this. @returns are most of the time redundant since the method description usually already says something about what's returned. But even then, it might be useful to use a @return for exceptional paths, like this method returns null if yadayada. You could change the checkstyle to only report a warning in such cases, instead of an error. This way, you get the desired warning effect, but the error is less annoying. Jan-Kees 2008/12/9 Simon Kitching [EMAIL PROTECTED]: I would also prefer to change the checkstyle rules to ignore missing @param and @return comments. Sometimes params really are obvious enough not to be documented, and in some other cases it is better to document them as part of the main method description rather than a separate tag. So blindly enforcing this check doesn't seem helpful... 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 [EMAIL PROTECTED]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? -- View this message in context: http://www.nabble.com/JavaDoc-and-checkstyle-tp20803530p20911066.html Sent from the My Faces - Dev mailing list archive at Nabble.com.
Re: JavaDoc and checkstyle
+1 Simon Kitching schrieb: I would also prefer to change the checkstyle rules to ignore missing @param and @return comments. Sometimes params really are obvious enough not to be documented, and in some other cases it is better to document them as part of the main method description rather than a separate tag. So blindly enforcing this check doesn't seem helpful... 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 [EMAIL PROTECTED]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?
Re: JavaDoc and checkstyle
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 [EMAIL PROTECTED]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?
Re: JavaDoc and checkstyle
That and rewriting any XML schema by hand. That was a funny one. Bruno 2008/12/9 Simon Kitching [EMAIL PROTECTED] 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 [EMAIL PROTECTED]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?
Re: JavaDoc and checkstyle
hello simon, i already brought up this topic at [1] did it happen again? if so: maybe it's helpful to write a general e-mail to the dev list and/or a wiki about this topic. regards, gerhard [1] http://www.nabble.com/Re%3A--JSF-2.0--Package-structure-for-Facelets-integration-p20798004.html 2008/12/9 Simon Kitching [EMAIL PROTECTED] 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 [EMAIL PROTECTED]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
Re: JavaDoc and checkstyle
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 [EMAIL PROTECTED]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 [EMAIL PROTECTED]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?
Re: JavaDoc and checkstyle
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. Regards, ~ Simon On Tue, Dec 9, 2008 at 10:06 AM, Simon Kitching [EMAIL PROTECTED]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 [EMAIL PROTECTED]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?
Re: JavaDoc and checkstyle
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 [EMAIL PROTECTED] mailto:[EMAIL PROTECTED] 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 [EMAIL PROTECTED] mailto:[EMAIL PROTECTED]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?
Re: JavaDoc and checkstyle
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 [EMAIL PROTECTED]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 [EMAIL PROTECTED] mailto:[EMAIL PROTECTED] 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 [EMAIL PROTECTED] mailto:[EMAIL PROTECTED]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?
Re: JavaDoc and checkstyle
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 [EMAIL PROTECTED] 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 [EMAIL PROTECTED]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 [EMAIL PROTECTED] mailto:[EMAIL PROTECTED] 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 [EMAIL PROTECTED] mailto:[EMAIL PROTECTED]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? --
Re: JavaDoc and checkstyle
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 [EMAIL PROTECTED]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? Regards, ~ Simon
