Uploaded image for project: 'OFBiz'
  1. OFBiz
  2. OFBIZ-9144

refactor javadocs in OFBiz to be standards compliant

    Details

    • Type: Improvement
    • Status: Closed
    • Priority: Minor
    • Resolution: Fixed
    • Affects Version/s: Upcoming Release
    • Fix Version/s: 16.11.02
    • Component/s: ALL COMPONENTS
    • Labels:
      None
    • Sprint:
      2016 - OFBiz Community Day 4

      Description

      The OFBiz javadocs are not standard compliant and not legally correct which means that generating javadocs would fail. As a temporary workaround we added to the gradle build script:

       javadoc.failOnError = false

      However, the root solution would be to fix all the errors in javadocs and eventually remove the above code snippet from gradle. For more about compliance with javadocs you can read javadoc style document

      The best way to fix this issue is by:

      1. running "./gradlew javadoc"
      2. fixing the javadoc errors
      3. running "./gradlew javadoc" again and ensuring the errors are gone

      This is a large task (might need to be broken down to many sub-tasks). Any help is greatly appreciated!

        Issue Links

          Activity

          Hide
          taher Taher Alkhateeb added a comment -

          This is a little bash code snippet that I use to quickly review the errors and fix them

          ./gradlew javadoc 2> javadoc.log
          grep error javadoc.log > javadoc_errors.log
          rm javadoc.log
          

          Then I view the javadoc_errors.log and fix it line by line

          Show
          taher Taher Alkhateeb added a comment - This is a little bash code snippet that I use to quickly review the errors and fix them ./gradlew javadoc 2> javadoc.log grep error javadoc.log > javadoc_errors.log rm javadoc.log Then I view the javadoc_errors.log and fix it line by line
          Hide
          taher Taher Alkhateeb added a comment -

          Committed a large fix in r1774154.

          Show
          taher Taher Alkhateeb added a comment - Committed a large fix in r1774154.
          Hide
          mbrohl Michael Brohl added a comment -

          Are you still working on this issue, Taher Alkhateeb?
          Else I will fix the few remaining issues.

          Show
          mbrohl Michael Brohl added a comment - Are you still working on this issue, Taher Alkhateeb ? Else I will fix the few remaining issues.
          Hide
          taher Taher Alkhateeb added a comment -

          Hi Michael,

          By all means .. please help! Please note however there are at least hundreds and probably thousands of javadoc errors left. So this might take a while.

          Show
          taher Taher Alkhateeb added a comment - Hi Michael, By all means .. please help! Please note however there are at least hundreds and probably thousands of javadoc errors left. So this might take a while.
          Hide
          mbrohl Michael Brohl added a comment -

          Are you sure they are that many? I checked with the above bash commands and got 101 error lines.

          I'll work on them and we'll see...

          Show
          mbrohl Michael Brohl added a comment - Are you sure they are that many? I checked with the above bash commands and got 101 error lines. I'll work on them and we'll see...
          Hide
          taher Taher Alkhateeb added a comment -

          There is probably a flag somewhere but by default gradle shows a max of 100 javadoc errors

          Show
          taher Taher Alkhateeb added a comment - There is probably a flag somewhere but by default gradle shows a max of 100 javadoc errors
          Hide
          mbrohl Michael Brohl added a comment -

          This is a patch to turn off the strict javadoc checks.

          Show
          mbrohl Michael Brohl added a comment - This is a patch to turn off the strict javadoc checks.
          Hide
          mbrohl Michael Brohl added a comment -

          Committed a bunch of corrections in r1774815.

          I've attached a patch which deactivates the strict checks, see http://blog.joda.org/2014/02/turning-off-doclint-in-jdk-8-javadoc.html.

          Maybe we should put this in to be able to generate the javadocs without errors and work on to clean them up in parallel?

          Show
          mbrohl Michael Brohl added a comment - Committed a bunch of corrections in r1774815. I've attached a patch which deactivates the strict checks, see http://blog.joda.org/2014/02/turning-off-doclint-in-jdk-8-javadoc.html . Maybe we should put this in to be able to generate the javadocs without errors and work on to clean them up in parallel?
          Hide
          taher Taher Alkhateeb added a comment -

          Yeah good idea. Does this flag stop you from detecting these errors though? If yes, I think it's best to mention how to temporarily turn it off in the description of this JIRA for those interested in helping. Nice research and nice catch

          Show
          taher Taher Alkhateeb added a comment - Yeah good idea. Does this flag stop you from detecting these errors though? If yes, I think it's best to mention how to temporarily turn it off in the description of this JIRA for those interested in helping. Nice research and nice catch
          Hide
          mbrohl Michael Brohl added a comment - - edited

          Yes, the flags does not show any errors in the log. I have tested this and it works.

          If we want this to be in the codebase I will commit it during the day and write a short comment how to disable.

          Show
          mbrohl Michael Brohl added a comment - - edited Yes, the flags does not show any errors in the log. I have tested this and it works. If we want this to be in the codebase I will commit it during the day and write a short comment how to disable.
          Hide
          pfm.smits Pierre Smits added a comment -

          I suggest to put that kind of instruction in the wiki rather than as a comment to this issue. After this issue has been closed this will drift into oblivion.

          Show
          pfm.smits Pierre Smits added a comment - I suggest to put that kind of instruction in the wiki rather than as a comment to this issue. After this issue has been closed this will drift into oblivion.
          Hide
          mbrohl Michael Brohl added a comment -

          Of course, Pierre. I just created a reminder issue for this and overall Javadoc quality assurance in OFBIZ-9148.
          Be patient.

          Show
          mbrohl Michael Brohl added a comment - Of course, Pierre. I just created a reminder issue for this and overall Javadoc quality assurance in OFBIZ-9148 . Be patient.
          Hide
          mbrohl Michael Brohl added a comment -

          Committed another bunch of corrections in r1774922.

          There are many, many warnings but we now have no errors left in the Javadocs as far as I can see.
          So in the sense of the issue, we can close.

          Wdyt, Taher Alkhateeb?

          Show
          mbrohl Michael Brohl added a comment - Committed another bunch of corrections in r1774922. There are many, many warnings but we now have no errors left in the Javadocs as far as I can see. So in the sense of the issue, we can close. Wdyt, Taher Alkhateeb ?
          Hide
          taher Taher Alkhateeb added a comment -

          Wonderful work! Thank you Michael.

          I suggest if everything is okay to also remove from build.gradle the "failOnError" flag so that if anyone submits invalid javadocs in the future the buildbot would fail.

          Show
          taher Taher Alkhateeb added a comment - Wonderful work! Thank you Michael. I suggest if everything is okay to also remove from build.gradle the "failOnError" flag so that if anyone submits invalid javadocs in the future the buildbot would fail.
          Hide
          taher Taher Alkhateeb added a comment -

          And yeah if all errors are removed, we can tolerate warnings (or leave them for another JIRA)

          Show
          taher Taher Alkhateeb added a comment - And yeah if all errors are removed, we can tolerate warnings (or leave them for another JIRA)
          Hide
          jacques.le.roux Jacques Le Roux added a comment -

          for the hard work, thanks Michael!

          +1 for capturing any error by removing the "failOnError" flag

          Show
          jacques.le.roux Jacques Le Roux added a comment - for the hard work, thanks Michael! +1 for capturing any error by removing the "failOnError" flag
          Hide
          mbrohl Michael Brohl added a comment -

          Thanks, Jacques.

          The hardest work was done by Taher, I was just finishing the remaining issues.

          Show
          mbrohl Michael Brohl added a comment - Thanks, Jacques. The hardest work was done by Taher, I was just finishing the remaining issues.
          Hide
          mbrohl Michael Brohl added a comment -

          I have changed to

          javadoc.failOnError = true

          in trunk r1774933.

          Show
          mbrohl Michael Brohl added a comment - I have changed to javadoc.failOnError = true in trunk r1774933.
          Hide
          taher Taher Alkhateeb added a comment -

          Minor point, but deleting this flag is the same as setting it to true (default value)

          Show
          taher Taher Alkhateeb added a comment - Minor point, but deleting this flag is the same as setting it to true (default value)
          Hide
          mbrohl Michael Brohl added a comment -

          Yes, I have noticed that you suggested to remove it.
          I think it's a good reference to leave it in but can also remove if we want to keep the build file as light as possible.

          Show
          mbrohl Michael Brohl added a comment - Yes, I have noticed that you suggested to remove it. I think it's a good reference to leave it in but can also remove if we want to keep the build file as light as possible.
          Hide
          jacques.le.roux Jacques Le Roux added a comment -

          I'm now used to see Taher doing the hardest tasks, so I stopped to congratulate him

          Show
          jacques.le.roux Jacques Le Roux added a comment - I'm now used to see Taher doing the hardest tasks, so I stopped to congratulate him
          Hide
          jacques.le.roux Jacques Le Roux added a comment -

          Moot point to me for true over removing, can be removed later. I know Taher likes to remove deprecated things ASAP And there is some sence it it, things are then clearer...

          Show
          jacques.le.roux Jacques Le Roux added a comment - Moot point to me for true over removing, can be removed later. I know Taher likes to remove deprecated things ASAP And there is some sence it it, things are then clearer...

            People

            • Assignee:
              mbrohl Michael Brohl
              Reporter:
              taher Taher Alkhateeb
            • Votes:
              0 Vote for this issue
              Watchers:
              4 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Development

                  Agile