This discussion is archived
2 Replies Latest reply: Nov 18, 2010 6:54 AM by aksarben RSS

Synchronize Java code and Documentation

813611 Newbie
Currently Being Moderated
Hello,

I am looking for an solution to Synchronize Java code and its api documentation. When my team make some changes in Java code, I want that my documentation should automatically synchronized to the new code, if this is not possible than there might me some way by which whenever i read documentation, documentation can point that this code needs to be updated. Something like a plugin between documentation and eclipse.
We use Java with Eclipse and Maven.

Thanks
  • 1. Re: Synchronize Java code and Documentation
    JoachimSauer Journeyer
    Currently Being Moderated
    You can modify your IDE settings to treat JavaDoc errors (or even missing attribute descriptions) as errors. I know Eclipse can do that.

    Alternatively, add a JavaDoc build step to your build on your continuous-integration system and make it break on warnings.

    Or: write your code in a way that minimizes the need for documentation, because after all: if your code and your documentation disagree, then they are probably both wrong.
  • 2. Re: Synchronize Java code and Documentation
    aksarben Journeyer
    Currently Being Moderated
    In a team environment, I would strongly recommend enforcing documentation updates via the build process. There are lots of ways to do this: Ant tasks, Maven POM files, etc. The principle is the same, though, however you do it: Have the build process create/update the documentation automatically. Don't rely on people doing it manually, because they'll eventually forget when they're rushing to meet a deadline. And if classes/methods are missing Javadoc comments, have the build process fail, so you can't produce executables with incomplete documentation.

Legend

  • Correct Answers - 10 points
  • Helpful Answers - 5 points