if you didn’t notice, GoogleCode now allows online editing of code directly in the browser, when you look at a file, theres a “edit” link on the top that allows you editing the file. Although I think its not so good trying to apply fixes without checking them in the IDE , now it should be possible to anyone to extend and complete the jME3 javadocs even when they don’t know about svn. I guess everybody who has done something in jME3 can contribute to the docs even if its not the most technical stuff, theres still lots of stuff missing in them.
Creating javadoc is simple, you just need to open a java source file, create a comment starting with /** right before a method and annotate its parameters and return value (if there is one), see an example:
[java]
/**
Multiplies the two values
@param valueOne The first value
@param valueTwo The second value
@return The product of value one and value two
*/
public float multiply(float valueOne, float valueTwo){
Do note that you can commit your changes without explicit commit access. If you browse the source and make an edit, your change will be submitted as a new ticket in our issue tracker and the developers get to review the change before committing it in an update. This will enable us to accept a large volume of JavaDoc contributions without making commit-access completely unmanageable.
Google says this should work. @madjack, if you could be the first to test this for us that would be great.
Oh btw, I noticed in some recent patches that there was a lot of character spacing fixing. Things like if a=b being fixed into if a = b… Would that be allowed or should we wait until there’s a real bug fix so not to waste bandwidth?
Well don’t bother doing that, I don’t know for the others team members but I usually format and fix the import on every java file i commit. It’s just two short cuts in JMP/netbeans/Eclipse…doing it by hand in google editor makes no sense.
Don’t worry, it was never my intention to go through a file and fix the spacing (I know you can use jMP for that) but if I do see one or two I might be tempted.
I wanted to add little things to Application.java but I’m only getting the partial file displayed in the browser. Can someone verify it’s not just me? Here it suddenly cuts at line 114. I’m not too keen on editing as I’m not sure how googlecode will react. I’m afraid it might truncate the file. I know it can’t really break the file (hopefully not), but I’m not willing to take a chance.
That line says:
[java] throw new IllegalStateException("Can only[/java]
and that’s it…
I tried other files and they were displaying correctly… shrug
madjack said:
There seem to be an issue with editing.
I wanted to add little things to Application.java but I'm only getting the partial file displayed in the browser. Can someone verify it's not just me? Here it suddenly cuts at line 114. I'm not too keen on editing as I'm not sure how googlecode will react. I'm afraid it might truncate the file. I know it can't really break the file (hopefully not), but I'm not willing to take a chance.
That line says:
[java] throw new IllegalStateException("Can only[/java]
and that's it... :/
I tried other files and they were displaying correctly... *shrug*
Confirmed. I just had the same, the first time i wanted to add a patch.
RenderState.java
ONly the top 3rd showed in the edit window. Couldnt scoll down with cursors either.
Also after a few reloads of the page the edit option was gone.
At the risk of showing up too late for this party, I had some questions:
I’m presently not a contributor, so is editing the Google Code a legit way for me to contribute to the JavaDocs?
If so:
Would devs prefer a series of updates to a given file to be batched together (as opposed to getting say a separate ticket for each method)?
When I attempted it, using Chrome, I didn’t observe the truncation problem noticed by madjack & durandal - has this been fixed? Or maybe it was a browser specific problem (stands to reason the made sure Google Code pages behave in Chrome)?
While the method names are rather self descriptive, I noticed that the documentation for things like [java]ColorRBGA.mult(…)[/java] and [java]ColorRBGA.multLocal(…)[/java] doesn’t explicitly indicate that the latter has a side effect on object state - is this a deliberate omission of detail?
Similarly are methods like [java]ColorRBGA.getRed()[/java] intentionally undocumented, or were they just low priority & thus left for rainy days?
At least every public method should be documented yes.
So if there is missing javadoc it’s not intended it’s mostly lack of time (laziness :p)
You’d better make one contribution for the whole file as Google code will generate a patch file that will be added to the issue list.So it’s easier to apply if there is one patch per file.
Don’t hesitate to remind us to apply it in this thread because we might not see every issue added to the tracker (…laziness :p)
@jonathan-pikalek said:
One more question - what's the protocol if I find existing Javadoc that seems to contradict the code? Possibilities that come to mind:
1) Try to change the doc to reflect the code
2) Try to chage the code to reflect the doc
3) Leave both code & doc as is & bring it to the attention of devs some other way (if so, please elaborate)
