New way to do JavaDoc?

What do you guys think of using something like this to replace the JavaDocs?


I am new to github and AsciiDoc so I am not sure if this is possible but what I am thinking is since the wiki works so well on github where the wiki is immediately updated after the commit, this could be used to do the same for the JavaDocs. So everytime a file is changed on the jMonkey github repository the javadocs can be updated automatically.

Does this sound unreasonable?

1 Like

This is not the process that would trigger the generation, though, right? It’s just a way of including AsciiDoc style markup in javadoc comments. (Which I’m kind of against, by the way.)

…and if you are going to find some way to trigger javadoc to be run then it might as well also just commit them to the github pages as they are. I do this manually for several of my projects.

…since github can host the javadoc natively.

We’d just need a process to run when things are committed. Or when we branch… I suppose we could have Travis upload the javadocs when we release just like we upload to bintray, etc… Maybe it’s already doing that and I’m just oblivious.

1 Like

It would take a commit to generate and if thereafter a page is not touched nothing would change is how I see it. It would be a monumental task to convert all the files over though. Doing so would trigger the docs to update though. I wouldn’t use them as official until the complete conversion was finished.

What I am after is a way to always have a current javadoc so we can link to it from the wiki rather than linking to a raw java file in the jMonkey repository.

Right now If I make changes to the jMonkey repository file someone has to manually update the online javadoc linked to from the forum. Just thought it would make more sense to automate it like the wiki and asciidoc is already being used so seemed to make sense.

Do you manually update your linked to javadocs?

1 Like

Actually we do have that already

the gh-pages branch of this repo is actually the javadoc accessible from the menu up here ^.
It doesn’t seem to be automated but I guess we could do that.

1 Like

That repository is what I was talking about.

Having a commit update the javadoc would be just fine.

1 Like

…which has nothing to do with what you linked, by the way.

AsciiDoclet is a javadoc plugin to use AsciiDoc style markup in your javadoc comments. It has nothing at all to do with autorunning javadoc when .java files change or whatever. ie: it’s completely useless for this conversation.

1 Like

Also, updating the online javadoc whenever a file changes is a bad idea. The online javadoc should correspond to some release that users can actually download. Otherwise, the javadoc is always wrong.

The only people totally-up-to-date-this-second javadoc would be useful for are folks building from source… who can already have the most up-to-date javadoc with what they checked out just by building the javadoc.

We definitely should update the javadoc as part of our release process, though.

1 Like

I know what it does. Just thought it would consistent with the direction the wiki has taken is all.

1 Like

javadoc is not a wiki. Javadoc is separate from a wiki… We might go through a 10 more different wiki servers and a 100 more wiki markup styles with this same codebase. That’s why I’m 1000000000000000000000000000000000000000000000000000000000000% against including the “markup of the day” in javadoc. It’s crazy, in my opinion.

1 Like

No problem.

Most people I would venture to guess go right for the latest SDK or build. Having a javadoc that matches release is the correct way to go but there’s years between releases. The only way to overcome that is to have 2 javadocs, 2 wikis right? People who use the latest versions could use the latest docs and wiki.

The github docs for the jMonkey repository does ask developers to update the wiki if they make changes so technically that cant be done the way things are now. Having the new docs autoupdate would fit right into that model. Asciidocs doesn’t have to be used for them, just was an idea.

1 Like

javadoc should be updated with releases. We should have one for the last stable and one for the current alpha/beta chain (which is effectively ‘stable’ right now).

So we should be keeping a 3.0 javadoc and a 3.1 javadoc online right now but we don’t.

The wiki can be more up to date than what’s released. There’s not really another good way to do that and we should not discourage wiki updates for any reason… they are rare enough as it is.

1 Like

The current repositories can be branched after the next stable release to keep things simple right? After bringing the wiki up to date that is. Its starting to look pretty good now.

Everything can move forward from there. No one updates their wiki and releases it real time. The current situation should be considered temporary since it was caused by a host change requiring immediate attention. A contribute page can be added to the jmonkey site that clarifies the process.

1 Like