Display JavaDocs on GitHub

Question

I\'m looking for a way to convert the javadocs from my open source project (generated in Eclipse) to GitHub MarkDown, or come up with some other s

Answer 1

Do NOT check Javadocs into the source control for your project

Especially not into the master branch! I followed the other answers to this question for about a year before deciding it was a really bad idea. Why?

1. It made it too difficult to review diffs. I even made a script (see below) to update only the Javadoc pages that substantially changed, but it still was a mess.

2. It fooled IntelliJ's refactoring tools. I just tried to change .x() to .getX() and had to approve/reject every "x" in the Javadocs. Maybe I forgot to exclude the folder in IntelliJ, but if you ever use sed/grep/find on your project, you have to remember to exclude it every time.

3. It adds a bunch of data in git that just shouldn't be there, potentially making pull and clone commands take longer... FOREVER! Even if you later "remove" the folder, it's still stored in git.

Where should javadocs go?

It's probably best to post them on https://javadoc.io/, your web site, or AWS or heroku. If you must check javadoc into source control, make a separate project just for Javadocs so you'll never need to look at the diff. You can follow other people's answers for how to do this.

"I read your post, but I'm doing it anyway"

Here's my script to update fewer javadocs. It only copies files with substantial changes from the target/apidocs folder to the docs/apidocs folder. It also adds new files and deletes no longer used ones. I think I used poor names, newfile and oldfile, but it works. I mean, it wasn't enough to justify checking javadoc into my project's source control, but it helps.

#!/usr/bin/env bash

# -I means ignore lines matching a regular expression
# -q means "quiet" - only tell whether files differ or not
# -r means "recursive" - explore subdirectories
# -N means "treat absent files as empty" which makes absent files show up in Quiet mode.
diff -I '
     
 

        
热议问题