Fwd: License headers inside Javadoc comments
Just a forward to complete the records. Forwarded Message Subject:Re: License headers inside Javadoc comments Date: Fri, 26 Jan 2024 15:38:29 +0200 From: James Turton To: P. Ottlinger , d...@creadur.apache.org CC: dev Thanks Phil. Here's some background [1] which comes from before I was involved with Drill. What they wanted was for the license header checker to accept, in .java files, /* * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file * distributed with this work for additional information etc. but reject /** * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file * distributed with this work for additional information etc. Notice the two asterisks that open the Java comment block in the second form thereby making it a Javadoc comment that will appear in generated Javadoc. There are no longer any examples of the latter in Drill but this has been enforced by the addition of the license-maven-plugin. I got here because I want to remove that plugin, which essentially duplicates RAT, in favour of another (with exactly the same name :() that can generate license and notice information for our third party code. This last task is what I'm really doing, the Javadoc license header rejection matter is yak shaving that came up on the road. So my yak shaving question is: if I make RAT Drill's only license header checker then could I make it reject license headers of the second form? Even if I can't I'm inclined to make it the only header checker since I think that it's in any case mandatory and authoritative. But in an effort to retain the work of the previous Drill developers I'm trying to preserve what they implemented. 1. https://issues.apache.org/jira/browse/DRILL-6320 On 2024/01/26 14:06, P. Ottlinger wrote: Hi James, thanks for reaching out! Am 26.01.24 um 08:21 schrieb James Turton: I'd like to ask about a feature to prevent RAT from allowing license headers to appear inside Javadoc comments (/**) while still requiring them in Java comments (/*) in .java files. Currently the Drill project makes use of com.mycila.license-maven-plugin to reject licenses in Javadoc comments because the developers at the time didn't want license headers cluttering the Javadoc website that is generated from the source. Are you aware of a general view on Apache license headers appearing in Javadoc pages? If preventing them from doing so is a good idea, could this become a (configurable) feature in RAT? could you be so kind to provide an example of what you want to achieve and how your use case looks like? I'm afraid I do not really understand what you mean with javadoc-specific licenses? At the moment we don't have a file specific parsing to exclude comments - is that what you want to achieve? On the other hand if a license header is needed per file, it has to be somewhere in the sources ;) Thanks, Phil
Re: License headers inside Javadoc comments
Thanks Paul I don't know how to configure the license plugin. But, I do suspect a Python file (or shell script) could make a one-time pass over the files to standardize headers into whatever format the team chooses. Only the first line of each file would change. I put more information in my reply to the RAT devs but exactly this. Adding a grep or a sed command to the build or to the release instructions would surely be sufficient. I will likely replace the license-maven-plugin that was brought in with something that does other needed things, like report our third party licenses. On 2024/01/26 09:59, Paul Rogers wrote: Hi James, For some reason, Drill started with the license headers in Javadoc comments. The (weak) explanation I got was that we never generate Javadoc, so it didn't really matter. Later, we started converting the headers to regular comments when convenient. If we were to generate Javadoc, having the license at the top of each page as the summary for each class would probably not be something that anyone finds useful. I don't know how to configure the license plugin. But, I do suspect a Python file (or shell script) could make a one-time pass over the files to standardize headers into whatever format the team chooses. Only the first line of each file would change. - Paul On Thu, Jan 25, 2024 at 11:22 PM James Turton wrote: Good morning! I'd like to ask about a feature to prevent RAT from allowing license headers to appear inside Javadoc comments (/**) while still requiring them in Java comments (/*) in .java files. Currently the Drill project makes use of com.mycila.license-maven-plugin to reject licenses in Javadoc comments because the developers at the time didn't want license headers cluttering the Javadoc website that is generated from the source. Are you aware of a general view on Apache license headers appearing in Javadoc pages? If preventing them from doing so is a good idea, could this become a (configurable) feature in RAT? Thanks James Turton
Re: License headers inside Javadoc comments
Thanks Phil. Here's some background [1] which comes from before I was involved with Drill. What they wanted was for the license header checker to accept, in .java files, /* * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file * distributed with this work for additional information etc. but reject /** * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file * distributed with this work for additional information etc. Notice the two asterisks that open the Java comment block in the second form thereby making it a Javadoc comment that will appear in generated Javadoc. There are no longer any examples of the latter in Drill but this has been enforced by the addition of the license-maven-plugin. I got here because I want to remove that plugin, which essentially duplicates RAT, in favour of another (with exactly the same name :() that can generate license and notice information for our third party code. This last task is what I'm really doing, the Javadoc license header rejection matter is yak shaving that came up on the road. So my yak shaving question is: if I make RAT Drill's only license header checker then could I make it reject license headers of the second form? Even if I can't I'm inclined to make it the only header checker since I think that it's in any case mandatory and authoritative. But in an effort to retain the work of the previous Drill developers I'm trying to preserve what they implemented. 1. https://issues.apache.org/jira/browse/DRILL-6320 On 2024/01/26 14:06, P. Ottlinger wrote: Hi James, thanks for reaching out! Am 26.01.24 um 08:21 schrieb James Turton: I'd like to ask about a feature to prevent RAT from allowing license headers to appear inside Javadoc comments (/**) while still requiring them in Java comments (/*) in .java files. Currently the Drill project makes use of com.mycila.license-maven-plugin to reject licenses in Javadoc comments because the developers at the time didn't want license headers cluttering the Javadoc website that is generated from the source. Are you aware of a general view on Apache license headers appearing in Javadoc pages? If preventing them from doing so is a good idea, could this become a (configurable) feature in RAT? could you be so kind to provide an example of what you want to achieve and how your use case looks like? I'm afraid I do not really understand what you mean with javadoc-specific licenses? At the moment we don't have a file specific parsing to exclude comments - is that what you want to achieve? On the other hand if a license header is needed per file, it has to be somewhere in the sources ;) Thanks, Phil
Re: License headers inside Javadoc comments
Hi James, thanks for reaching out! Am 26.01.24 um 08:21 schrieb James Turton: I'd like to ask about a feature to prevent RAT from allowing license headers to appear inside Javadoc comments (/**) while still requiring them in Java comments (/*) in .java files. Currently the Drill project makes use of com.mycila.license-maven-plugin to reject licenses in Javadoc comments because the developers at the time didn't want license headers cluttering the Javadoc website that is generated from the source. Are you aware of a general view on Apache license headers appearing in Javadoc pages? If preventing them from doing so is a good idea, could this become a (configurable) feature in RAT? could you be so kind to provide an example of what you want to achieve and how your use case looks like? I'm afraid I do not really understand what you mean with javadoc-specific licenses? At the moment we don't have a file specific parsing to exclude comments - is that what you want to achieve? On the other hand if a license header is needed per file, it has to be somewhere in the sources ;) Thanks, Phil OpenPGP_signature.asc Description: OpenPGP digital signature
Re: License headers inside Javadoc comments
Hi James, For some reason, Drill started with the license headers in Javadoc comments. The (weak) explanation I got was that we never generate Javadoc, so it didn't really matter. Later, we started converting the headers to regular comments when convenient. If we were to generate Javadoc, having the license at the top of each page as the summary for each class would probably not be something that anyone finds useful. I don't know how to configure the license plugin. But, I do suspect a Python file (or shell script) could make a one-time pass over the files to standardize headers into whatever format the team chooses. Only the first line of each file would change. - Paul On Thu, Jan 25, 2024 at 11:22 PM James Turton wrote: > Good morning! > > I'd like to ask about a feature to prevent RAT from allowing license > headers to appear inside Javadoc comments (/**) while still requiring > them in Java comments (/*) in .java files. Currently the Drill project > makes use of com.mycila.license-maven-plugin to reject licenses in > Javadoc comments because the developers at the time didn't want license > headers cluttering the Javadoc website that is generated from the > source. Are you aware of a general view on Apache license headers > appearing in Javadoc pages? If preventing them from doing so is a good > idea, could this become a (configurable) feature in RAT? > > Thanks > James Turton >
