"/**" comments that are not intended to be parsed by the javadoc tool should be considered as either an anti-pattern or a bug in my opinion. There is simply no sane reason in doing that. "/**" comments should be used only for javadocs and nothing more. For things that have nothing to do with javadocs, the "//" and the standard "/*" comments should be used.
A related, but different, issue is that javadoc syntax in non-javadoc comments is a problem too. Already saw many people using that in the form of "/* (non-javadoc) @see blahblah */" comments, but can occasionally be seen in other forms. This is an anti-pattern in my opinion. 2017-11-18 17:33 GMT-02:00 Lars Bruun-Hansen <[email protected]>: > I've noticed that AL2 license headers for Apache NetBeans in Java source > code files start with the Javadoc introducer, i.e. "/**" rather than just > "/*". Even on .c and .h files this is the case. > > I've checked how the IDE itself does it on a fresh project where you ask it > to apply some type of license header: It will - correctly - start with > "/*", not "/**". I've also looked around how other projects do it, for > example the JDK itself : all examples I've found use "/*". It was also only > a "/*" back in Hg days. > > By starting the license header with "/**" we are telling the Javadoc parser > that this is something it should pay attention to. Luckily on a standard > class source file, Javadoc will ignore such comment because it comes before > the package declaration. On a package-info file it won't be ignored, unless > another Javadoc entry follows it. > > It may be minor, but I think it should be fixed. Better now than later. > > Opinions on this? >
