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?
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.
http://jmonkeyengine-contributions.github.io/Lemur/javadoc/Lemur/
http://jmonkeyengine-contributions.github.io/Lemur/javadoc/LemurProto/
http://jmonkeyengine-contributions.github.io/zay-es/javadoc/zay-es/
http://jmonkeyengine-contributions.github.io/zay-es/javadoc/Zay-ES-Net/
ā¦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.
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?
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.
That repository is what I was talking about.
Having a commit update the javadoc would be just fine.
ā¦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.
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.
I know what it does. Just thought it would consistent with the direction the wiki has taken is all.
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.
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.
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.
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.