Open chenejac opened 1 year ago
The javadoc link from above references the use of package.html
. This seems a bit outdated and I am using package-info.java
instead.
The Java 7 documentation for package comment seems to be the clearest in this regard.
The Java 11 documentation for package comment is a bit more lacking in details.
The FAQ (See A19) describes some limitations that they decided to not fix.
From what I understand between all of this is that removing the license from the class and putting it in the package java doc will result in the following design and behavior:
package-summary.html
) will contain the copyright information.package-info.java
or a package.html
file must be created for every single package.package-info.java
appears to work for me.package.html
file does not appear to work for me.Is this the desired behavior?
The mavenllibs link above has practically no documentation and is specialized towards SonarSource. It utilizes pre-created licenses files that are specific to SonarSource and does not include the Vivo LICENSE file.
Their github project appears to be here:
Can someone list some popular projects using the approach with JavaDoc? After reading a little bit about that, it looks to me as the traditional way with preamble in all Java files is more safe for us. I am not a lawyer, but it looks as adding copyright and reference to license at the beginning of each source file is needed or at least a good practice - link. I think we should just make our preamble consistent, with a short text
/* $This file is distributed under the terms of the license in the LICENSE file in the root of this project$ */
@chenejac I found this after trying some different search strings this morning:
- Copyright.java (interface defining a few constants such as default copyright date, default owner, etc. as well as the full default copyright notice)
- CopyrightAnnotation.java (annotation type for marking code as copyrighted)
- CopyrightTaglet.java (taglet for adding "@copyright" tags in JavaDoc)
package org.sample.legal;
import com.sun.tools.doclets.Taglet; import com.sun.javadoc.*; import java.util.Map;
/**
private static final String NAME = "Copyright"; private static final String HEADER = "Copyright:";
This is not from Java files, but I happened to notice this while working on another issue.
There are .ftl
template files with lines like:
<#-- $This file is distributed under the terms of the license in /doc/license.txt$ -->
Which I neither see a doc
directory nor a license.txt
directory anywhere in the project source code.
My memory's a bit hazy, but I seem to recall that back a decade or so ago we had that license header line in any kind of source file with a commenting mechanism that permitted it. The old ant build would then replace the line with the contents of /doc/license.txt at build time, so the things like installed JSPs and later Freemarker templates would have the full license text automatically inserted. I think that was removed at some point because it made bug reports difficult when the line numbers would shift between the source tree and the webapps directory. It does seem like it would make sense to retain the license comments with an updated path to the license.
@kaladay I think we need the simple preamble
/* $This file is distributed under the terms of the license in LICENSE$ */
<#-- $This file is distributed under the terms of the license in LICENSE$ -->
@kaladay can you please investigate how alignment of files in accordance with two points above can be automatized in IDEs (through code formatter or in some other way)? I believe adding of license preamble might produce a lot of changed files, and maybe we can run that after the sprint together with code style alignment.
Also, it would be nice to have checking of the existence of license by using licence-maven-plugin - https://github.com/DSpace/DSpace/blob/main/pom.xml#L419
We decided to postpone this issue. It should be also discussed with VIVO Leadership group. Checking licence header might be part of building process (licence-maven-plugin). Aligning existing code base with licence header might be done by using some IDE plugins (https://www.jetbrains.com/help/idea/copyright.html#copyright-profile, https://www.baeldung.com/eclipse-copyright-header)
Is your feature request related to a problem? Please describe. There is a license preamble in a lot of Java files. Moreover, it is not in all Java files, meaning it is not consistent.
Describe the solution you'd like Remove those lines, and generate common JavaDoc preamble for all classes
Additional context @wwelling wrote: Looks to be a JavaDocs license header to not repeat license text in all files. Here are some links trying to discover the origin of these comments:
https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html#packagecomments https://mavenlibs.com/javadoc/api/org.sonarsource.license-headers/license-headers