I ran doxygen on the femtolib, just to see what it’d look like.
Even without comments, it produces useful information so it’s promising. Maybe a bit too much info, going into the internals.
It might be good to add the generated html to the IDE (and a keyboard shortcut to jump to the documentation of whatever is under the cursor) but still have the wiki with a simplified overview, for the newcomers who want to poke around before downloading. 
1 Like
I generally found wiki doc more friendly. It’s easy to add example and cross reference even for the users.
A nice example is how TIC80 wiki has been forged.
1 Like
I agree, it’s much friendlier than stock doxygen. I wish there was some way to generate the wiki from comments in the source, though.
2 Likes
You can disable parts.
You can completely disable the navbar or the tree view (or both if you’re a masochist).
Also if you run doxygen -l it generates a layout file (.xml) that you can use to prune the interface by setting visible="yes" to visible="no".
You can add custom .css and there’s probably even a handful of ways to tweak the .html in other ways.
I think I remember reading that you can get a copy of the .html page it uses as a base and then modify that to your liking, but it’s discouraged becuase that base could change between versions.
We (probably I) could add a guide on how to write Doxygen comments for people new to Doxygen if you want.
If you’ve had a skim of the PokittoLib source code before then you’ve probably encountered one or two because Doxygen is what generates this:
Part of the problem of wikis is the lack of control.
Anyone can write anything at any time - it’s harder to curate compared to having commits and PRs.
Addding non-API documentation to the Doxygen files isn’t actually that different to writing the wiki because it’s still Markdown, there’s just a few minor tweaks people would have to be aware of (page ids, title anchors and the subpage directive), and if it’s being commited and merged then the repo maintainer(s) can always add the bits that go missing when people forget.
This is kind of the big thing.
The way Wikis are set up on GitHub, someone would have to manually go through and add every function overload including type info.
Doxygen might not be as friendly if you aren’t used to using it,
but it does a lot more heavy lifting and it’s more customisable.
Unless there’s a .html to .md converter out there I can’t think of an easy way to handle it short of finding a Java parser and modifying it to generate Markdown.
1 Like
* Hagrid voice *
I shouldn’t have said that. I should not have said that…
2 Likes
I didn’t notice before, that wiki is seriously lacking type information.
It doesn’t say whether x, y and r are integers or floating points, or whether either are acceptable or even a mix of both.
And it doesn’t say whether color is a triple (3-tuple) of integers, a triple of floats, or some specific Colour class.
(Though I admit Lua’s own documentation doesn’t set a good precedent there. Nor does Python’s for that matter, so it’s possible this is common practice for duck-typed languages, which is a rather disturbing thought.)
Compare that to the PokittoLib API documentation where drawCircle completely specifies that x0, y0 and r are all int16_t.
Granted it’s missing a lot of detail in the explanation of the function, but that’s easy enough to add.
For an example of a more complete API documentation there’s the Arduboy2 library.
Its documentation of drawCircle specifies that x0, y0, r and color are all uint8_t, it details each of the parameters, states what it does and even provides the line number and file where the function is defined.
The only thing it’s missing is an example, though I don’t think that’s strictly necessary.
Some functions do have example code, like readUnitName.
And in case it makes a difference, yes Doxygen can have embedded images too, but that’s actually quite unusual for API documentation.
1 Like
@FManga Is the Java implementation supposed to simulate a particular version of Java, e.g. Java SE 7?
I’ve written some brief documentation for some of the functions and used Doxygen to generate some HTML to demonstrate what the API documentation could look like:
https://pharap.github.io/FemtoIDEDocumentationExample/
If you want to inspect the actual HTML, the repo is here:
Also sorry for the comment spamming on this thread.
2 Likes
Language-wise, I’m aiming for J2SE5 but there are some features from newer versions (like var declarations) while others are still missing (generics).
For the library, it has no specific target yet (I just implemented whatever was needed at the time), but it would be good to have some J2ME compatibility.
1 Like
Just added some documentation for java.util.
There’s still some missing documentation and some improvements that could be made, but this is just to demonstrate the idea to see what people think.
I’d like to clarify that actually writing the documentation and generating the html took less time than I spent waiting for it to be uploaded to GitHub.
(And that’s not just because I stole borrowed most of the comments from the official Java documentation.)
If anyone wants to see what the code looks like with the Doxygen comments, see here.
If anyone wants to see what the Doxyfile looks like, see here.
(The Doxyfile is actually much larger than it needs to be. I left some settings in to remind myself that they exist and I should investigate them.)
If you download that branch you can have a go at generating the documentation for yourself, you just need to navigate to FemtoIDE-add-doxygen-documentation/javacompiler on the command line and then run doxygen (either by having it in your %PATH% or by specifying the full path to doxygen.exe).
Type erasure probably means there’s going to be lots of void * in the output…
The closest way I can think to getting something like what Java does internally would be to generate a class that does everything with void * (or if Object exists, Object *) and then generate a template class that wraps the first class and just does loads of casting.
It sounds clunky and horrible, and it really is,
but that’s actually pretty much what Java does.
(And that’s why a lot of people don’t like type erasure.)
Some interesting links relevant to that, which might also be useful:
- http://www.cakoose.com/wiki/type_erasure_is_not_evil
- https://stackoverflow.com/questions/520527/why-do-some-claim-that-javas-implementation-of-generics-is-bad
It took quite a bit of digging but I found the documentation for it:
https://docs.oracle.com/javame/8.0/api/cldc/api/index.html
There’s actually several supported APIs it seems, more can be found here:
https://docs.oracle.com/javame/8.0/javame-apis.htm
At least I assume this is the same API you’re thinking of.
@FManga Is ScreenMode supposed to be private?
Edit
void setFlipped(boolean flipped)If set to true, the sprite will sprout rainbows
As entertaining as this is, somehow I don’t think this is right…
Now with added examples:
https://pharap.github.io/FemtoIDEDocumentationExample/
Specifically:
- https://pharap.github.io/FemtoIDEDocumentationExample/intervalometer.html
- https://pharap.github.io/FemtoIDEDocumentationExample/sincosgraphical.html
Just to prove that having easily accessible examples is possible.
The corresponding markdown is pretty easy to manage:
https://github.com/Pharap/FemtoIDE/tree/add-doxygen-documentation/javacompiler/examples
In this case it really was an almost exact copy and paste, the only extra things I had to do were to add the title anchors ({#intervalometer} and {#sincosgraphical}), fixup the image to the correct path and add the title anchors to the list in Examples.md.
(I don’t know what the technical name is for the ‘title anchors’, that’s just a name I made up.)
I’ve also added a bit of documentation for the femto packages,
but not much more that what was already on the wiki.
Is anyone actually convinced Doxygen is a good idea yet?
Or should I just scrap all this and let people go back to filling in the wiki?
Yup, so horrible I keep leaving it for later. 
That’s the one. It would be useful for porting old cellphone games to the Pokitto in the future, though I’m not sure of how viable that idea is.
Nope, I simply forgot to put the public and the code that checks if something can be accessed or not was temporarily disabled so I hadn’t noticed.
On the wiki it wasn’t too bad, since it was being written in a less formal way. I agree it doesn’t fit in the code or doxygen.
Looks great!
Doxygen comments are definitely a good idea, so feel free to send me what you’ve done already in a PR.
The only doubt I have is on using Doxygen itself. It would be good if FemtoIDE came with a documentation generator. There are a few doxygen-compatible ones I have to look into. One of them actually generates markdown.
For FemtoLib, this would be a huge help.
For Java’s libs, on the other hand, I’m undecided: with time, compatibility with the standard lib will increase and our documentation effort becomes redundant. A wiki documenting where the libraries diverge would probably be better, as anyone would be able to point out differences. The advantage of the wiki comes with the ability to document the behavior, instead of the API.
1 Like
It’s possible, but there’s two things that make it unlikely to happen.
Firstly, actually getting a copy of old Java phone game binaries is probably difficult.
Secondly, even if you found a binary and disassembled it (there are some fairly decent Java dissasemblers out there fortunately), you probably wouldn’t be able to publish it becuase it would probably be copyrighted.
Phone games don’t tend to be open source sadly.
Ah, that’s good. Adding public back was the right decision then.
I only found out because it wasn’t showing up in the output because private things are hidden by default (as they should be).
I somewhat disagree.
It’s an amusing joke but it’s absolutely no use to end users.
Particularly those poor (possibly hypothetical) people who are wondering why their screen isn’t ‘sprouting rainbows’. :P
Do you want just the documentation to the API,
or do you also want the Doxyfile and the examples folder?
You don’t necessarily have to document Femto with the same tool you provide to end users.
Though I’d like to point out that Doxygen is (as far as I know) completely JavaDoc compatible in its sytax, so it would somewhat make sense to use it.
The only difficult parts about using Doxygen are managing the Doxyfile (i.e. if you want to tweak the html output) and hosting the HTML, actually learning how to write documentation is pretty straightforward.
If you already know Markdown then you only need to learn about 10-20 commands to do decently detailed documentation.
A large number of commands are either escape codes, aliases for other commands, or they do really specific things (like \emoji, \vhdlflow, \startuml et cetera).
But then you still need a tool to render the Markdown.
That can also be done with markdown files in the Doxygen output if need be.
Though I think you’d be surprised at the number of differences.
Of the java.util and java.lang functions I’ve documented, at least 11 are non-standard so far.
Also if the code is documented as it’s written it’s a heck of a lot easier than trying to document it afterwards.
Doxygen output looks promising.
- What I would like to have is a link from the method description to the example that uses the method.
- I also think that because drawing commands are under the “mode” tree they are hard to find at first by browsing the class list. Maybe “Graphics” would be better?
- IMO “Class Hierarchy” is not necessary and only increases the UI clutter
1 Like
That can probably be done.
I didn’t attempt it at the time because I think the examples might be a bit complex for simply demonstrating individual functions.
That’s probably one for @FManga to decide, but I somewhat agree.
I think maybe split the difference and call it femto.graphics.modes,
perhaps with ScreenMode moved to be under femto.graphics.
It can probably be removed,
though it might make more sense to keep it later down the line depending on how the API evolves.
Edit:
Yeah, just a matter of generating the DoxygenLayout.xml file and setting visible to "no":
<tab type="classes" visible="yes" title="">
<tab type="classlist" visible="yes" title="" intro=""/>
<tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/>
<tab type="hierarchy" visible="no" title="" intro=""/>
<tab type="classmembers" visible="yes" title="" intro=""/>
</tab>
I won’t update the online version at the moment because uploading all the files via the UI takes forever (thanks to GitHub’s silly 100 file limit per upload) and I can’t be bothered to dig out my copy of command line git.
Instead, here’s a screenshot:
2 Likes
The first one is really easy: there’s packs with thousands of them on archive.org.
Given that they’re openly distributed (and assuming that isn’t a infringement in itself), then would disassembling+rebuilding them be an infringement? It would probably be safe to simply provide the tools for users to do the conversion themselves, like I did with gameboy games.
Sure, you can send them too.
That’s true.
I am surprised, I thought it’d be worse.
I think he meant having a subcategory called Graphics, not necessarily a package.
Oh. Right. Windows. 
Hi! I was planning my next features on my Ze-Launch game, and I noticed I’d love to ear a loud explosion when the Cannon fired. I saw somewhere that audio features were planned, but any idea about when?
Sorry, I might sound a bit demanding haha
1 Like