Code documentation

[Day]

Hi everybody,

is there some code documentation?
I didn't find any.

While setting up my dev environment for Oolite, I saw that the only IDE managing objective-c (I mean with at least auto-completion, and able to show method calls and callers) was on xcode on OSX.
Being on linux, I finally use vim + youcompleteme.

As it isn't yet enough, I used doxygen to create a doc on the source, including the calls' and callers' graphs.

Would some be interested in adding a doxygen documentation to Oolite?
If yes, I've commited a doxygen config file on my branch (named 'Doxyfile'), which is enough to have a guite good documentation of the current code, even with svg graphs you can pan and zoom.

[another_commander]

Never used Doxygen but I guess anything that helps improve the project would be welcome. If it's only one file that we need to add and we are sure that it works as intended, I would not mind including it. Hopefully someone will be able to double check and verify it before we import it.

[Day]

Well yes, it's only one config file which would be commited.

The documentation is generated with the command "doxygen <File name>", in a directory specified in the config file, currently "doxygen".

This documentation should ideally not be commited. FYI, the oolite doc is 742 mb heavy.
It may be generated automatically and then made available to everybody, or, as I do now, generated by dev as they see fit when they need it.

The doxygen file I uploaded on my branch is working for me, that's one test
Hmm, better test the svg graphs with firefox, as I found on Google that they not always work with IE or Chrome.

[another_commander]

Installed doxygen v1.8.9.1 on Windows and tested the file. The documentaiton gets generated, but I am getting a bunch of this:

Code: Select all

error: Problems running dot: exit code=-1, command='dot', arguments='"C:/OoliteProject/oogit/oolite/doxygen/html/inherit_graph_237.dot" -T
svg -o "C:/OoliteProject/oogit/oolite/doxygen/html/inherit_graph_237.svg" -Tcmapx -o "C:OoliteProject/oolite/
doxygen/html/inherit_graph_237.map"'

followed by this at the end of execution:

Code: Select all

error: Failed to rename file C:/OoliteProject/oogit/oolite/doxygen/html/SDL_2Comparison_8h__dep__incl.svg to C:/OoliteProject/oogit/oolite/doxygen/html/SDL_2Comparison_8h__dep__incl.svg.tmp!
lookup cache used 24151/65536 hits=454731 misses=24384
finished...

Everywhere in the generated docs where there is a link labeled "Here is the caller graph for this function", I click but nothing happens. What am I doing wrong? I generated the docs with this command:

Code: Select all

c:\OoliteProject\oogit\oolite>c:\doxygen\doxygen.exe .\Doxyfile

I ran this from the Oolite source tree root.

[another_commander]

OK resolved. The problem was that I did not have GraphViz installed. After I installed it and set its bin folder to be included in the path environment variable, all worked just fine. This is a really neat and helpful thing to have, especially for those who come in contact with the game's code for the first time. I'm all up for including the Doxyfile in the distribution.

Example:

[Day]

I think it would be helpful to have a wiki page on this, explaining how to generate the doc and what dependencies it needs.

[maik]

I think it would be helpful to have a wiki page on this, explaining how to generate the doc and what dependencies it needs.

Let me know if you want to add it yourself, I'll create an account then.

[Day]

Ok, I'll do it.
The same nick and email address would be nice.
Thank you.

[Cody]

Let me know if you want to add it yourself, I'll create an account then.

While you're at it, maik - I seem to have forgotten my Wiki password.

[maik]

Let me know if you want to add it yourself, I'll create an account then.

While you're at it, maik - I seem to have forgotten my Wiki password.

Done, and done.

[Cody]

Thank you kindly, your Wizardness!

[Day]

Thank you maik

Ok, I've created this page, what do you think?:
http://wiki.alioth.net/index.php/Developing_Oolite

[maik]

Good start, Day. Thank you!

[Day]

You're welcome

[another_commander]

Regarding the Windows port please note that everything that one needs to build the game (minus the optional doxygen part of course, which is about to be added now) can be found in the first post of this thread:
https://bb.oolite.space/viewtopic.php?f=8&t=5943

Apart from doxygen setup (which is used only for generating documentation), no additional instructions are required, no additional setups, it all can be copied/pasted as-is to the wiki page.

Edit: Note also that these instructions are already in the wiki in this page: http://wiki.alioth.net/index.php/Runnin ... rom_Source
Maybe all this stuff will have to be moved to the new Developing Oolite page? Having the same data in multiple pages can only lead to confusion.

Edit2: Creating a github account and forking the repository is not strictly necessary for getting on with development, unless you intend to generate pull requests from your changes. One can do development just fine without a github account and, if you look at the instructions for Windows, you will see that they are implying that no github account previously exists. I think this should be made clear, because reading Day's wiki page right now makes it look like one must do all these steps no matter what and this may end up disoucraging people who might otherwise just try to get started with hacking the game.