Remove blank Javadoc #1566
Remove blank Javadoc #1566
Conversation
This commit cleans up Javadoc that does not add information. It resolves ecj warnings: `Javadoc: Description expected after ...` It helps to prevent future empty javadoc by disabling missingJavaDoc warnings. This resolves `Javadoc: Missing ...` The modification is a result of regular expression search&replace: in files `*.java` (exclude org.eclipse.jdt.core.tests.model/workspace) `^[\s]*\*[\s]*(@return|@param[\s]*[^\s]+|@throws[\s]*[^\s]+)\R([\s]*\*[\s]*@|[\s]*\*/\R)` ->`$2` `^([\s]*\*[\s]*\R)([\s]*\*/\R)` ->`$2` `^[\S\t]*/\*\*\R[\s]*\*/\R` ->`` in files `org.eclipse.jdt.core.prefs` `org\.eclipse\.jdt\.core\.compiler\.problem\.missingJavadoc(Comments|Tags)\=[^\s]*` ->`org\.eclipse\.jdt\.core\.compiler\.problem\.missingJavadoc$1\=ignore`
|
I could use some help to understand what exactly was improved here.
@jukzi what do you expect JDT committers to do to ensure "better" javadoc in the future? Do we have agreement about "better" in the first place. E.g., I don't see a need to enforce any of this in internal packages, where I'm happy about every bit of documentation I find, even if some bits are missing. So, what is the long-term goal? |
There was a problem hiding this comment.
Something went wrong on this class!
Hint: you broke all line endings.
It seems this mass change was not quite as safe as assumed.
There was a problem hiding this comment.
I don't see i broke or even changed any line ending in this file:
this is screenshot from windows, using autocrlf. If something changed it may be a egit or jgit problem or the line endings might have been wrong before
There was a problem hiding this comment.
Of course it works on your machine :) but that's not the same as what you changed in git.
Please look at the change in github: it says for this file specifically: "Large diffs are not rendered by default."
Also the header of this file seems to say that you changed 32,528 lines. In cause of doubt, git is "the truth".
or the line endings might have been wrong before
"wrong" is a relative term, but yes, the file dangerously had mixed line endings before, since a recent commit added one \r\n. But now all are windows line ends in git, where it should be unix style.
There was a problem hiding this comment.
Being the person who introduced the original \r\n inadvertently I worry it is going to happen again. I copy + paste between windows and Linux VM frequently and this problem may recur since the tool (Vim) may be going out of the way to preserve line endings. Shouldn't eclipse have a setting or save action that strips away the \r ??
|
@stephan-herrmann This comment is not related to this PR and its effects! |
|
@akurtakov I'm all in favor of improving javadoc quality. Is the overall effort directed at all bundles, or only doc-bundles? Do we have a ticket to check if JDT-validations - when enabled - would detect all those errors that currently only surface when generating javadoc? This could help to ensure we are actually fixing the right problems. |
Not that I know of, my current goal here is to have JDT doc bundles from https://github.com/eclipse-platform/eclipse.platform.releng.aggregator/tree/master/eclipse.platform.common/bundles to https://github.com/eclipse-jdt/eclipse.jdt . That would allow JDT committers that are not Platform committers to be able to maintain docs without waiting for Platform committer to push. |
@stephan-herrmann i went throughout all repositories in platform workspace. Actually for this repository no preferences where changed. A bad tag is an error while a missing tag is not / depends on preferences. Both empty tags and empty lines are boiler plate. Typically that boiler plate was added with a quick fix to add missing tags, without actually documenting the parameters which does not help at all. |
Is that why we don't have an issue filed in JDT?
And your PR description was just the same for all repos, irrespective of actual changes, right?
Where do you see this difference? JDT can report missing tags and missing descriptions. It seems that in all our projects both problems are configured to ignore. This means that future editing will run the same risk of creating meaningless javadoc.
I didn't say that empty tags are good, just that no tag is not better. So, what was the real goal of this change? From Alex's links I seem to understand you started by fighting problems causing the javadoc tool to fail. Which are they exactly? But it seems you ended up changing also things which don't matter for the tool? After asking all kinds of questions, these are my concerns:
|
|
Please boil it down to a request: do you want mixed line endings and boiler plate empty lines back?
|
|
Maybe we could add .gitattributes
to force unix style on .java files. https://bugs.eclipse.org/bugs/show_bug.cgi?id=342372
?
… Am 17.11.2023 um 05:25 schrieb Srikanth Sankaran ***@***.***>:
@srikanth-sankaran commented on this pull request.
On org.eclipse.jdt.core.tests.model/src/org/eclipse/jdt/core/tests/formatter/FormatterRegressionTests.java:
Being the person who introduced the original \r\n inadvertently I worry it is going to happen again. I copy + paste between windows and Linux VM frequently and this problem may recur since the tool (Vim) may be going out of the way to preserve line endings. Shouldn't eclipse have a setting or save action that strips away the \r ??
—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you were mentioned.
|
Sounds good to me, but as I'm on linux I don't have experience with Also we should first agree on what to do with the existing files that do contain one or more windows line ending. Interestingly, of those 127 files, 120 reside in Here's the list of files I suggest to fix in one go: |
|
@msohn is there any best-practice to avoid mixed line endings checked in for .java files? |
|
https://www.aleksandrhovhannisyan.com/blog/crlf-vs-lf-normalizing-line-endings-in-git/
|
All the other recommendations only target how files are checked out. Is there no way to force conversion to LF on check in or rejecting CRLF? |
|
You can batch convert CRLF to LF on Windows with File -> Convert Line Delimiters -> Linux, if that was the question. "On save" you can enable AnyEdit to do that, assuming your workspace / project is set to LF by default.
|
|
The question is if commits can be automatically rejected or autofixed if somebody does it wrong. |
|
That's what git would do automatically, once configured, as explained by Matthias above. |
|
that only affects git checkout |
Nope, see
|
|
You can check line endings in the repo using If you would still use Gerrit (;-)) you could use its uploadvalidator plugin which allows to reject pushes containing text files using Windows line endings [1]. You could setup a CI job which uses the output of |
Remove blank Javadoc
This commit cleans up Javadoc that does not add information.
It resolves ecj warnings:
Javadoc: Description expected after ...It helps to prevent future empty javadoc by disabling
missingJavaDoc warnings. This resolves
Javadoc: Missing ...The modification is a result of regular expression search&replace:
in files
*.java(exclude org.eclipse.jdt.core.tests.model/workspace)^[\s]*\*[\s]*(@return|@param[\s]*[^\s]+|@throws[\s]*[^\s]+)\R([\s]*\*[\s]*@|[\s]*\*/\R)->
$2^([\s]*\*[\s]*\R)([\s]*\*/\R)->
$2^[\S\t]*/\*\*\R[\s]*\*/\R->``
in files
org.eclipse.jdt.core.prefsorg\.eclipse\.jdt\.core\.compiler\.problem\.missingJavadoc(Comments|Tags)\=[^\s]*->
org\.eclipse\.jdt\.core\.compiler\.problem\.missingJavadoc$1\=ignore