Developer Documentation

[hiran]

We now have a new site https://ooliteproject.github.io/oolite/

It contains developer documentation. So far this is the Doxygen generated stuff, but we can extend it to hold more than that if we want to. As this documentation can easily be updated with the code I do not believe this would replace the wiki. Instead it can complement what we have and is auto-generated with each code change so it should always be up to date.

[another_commander]

Regarding entry points: The one in the Cocoa folder is for the Mac build and the one in the SDL folder is for the Windows and Linux ones. Right now there seems to be a mistake in the links in the generated documentation and they both point to the Cocoa main.m.

[hiran]

Thank you for the hint. While I revisited that code anyway, I tried to understand bits and place that into into a Doxygen style comment.
But now look what happened: The two entry points are not equivalent.

Should this be the answer to the question raised here?
https://bb.oolite.space/viewtopic.php?p=290063#p290063

[another_commander]

I would be genuinely surprised if that was the answer to the question you linked to.

[hiran]

I would be genuinely surprised if that was the answer to the question you linked to.

I am surprised, too. But I cannot find a better explanation.

So far it looks to me like the linux/windows version processes one command line parameter, whereas the Mac version processes none.
Where else could command line evaluation happen?

[another_commander]

So far it looks to me like the linux/windows version processes one command line parameter, whereas the Mac version processes none.

That is correct. -load is available only for the GNUstep builds.

[hiran]

So far it looks to me like the linux/windows version processes one command line parameter, whereas the Mac version processes none.

That is correct. -load is available only for the GNUstep builds.

The even more puzzling part is: what happened to all the other command line options?
https://wiki.alioth.net/index.php/Hidde ... parameters
I cannot believe they were documented but did not exist.
I also cannot believe they were lost through code changes and noone noticed.

[hiran]

The even more puzzling part is: what happened to all the other command line options?
https://wiki.alioth.net/index.php/Hidde ... parameters
I cannot believe they were documented but did not exist.
I also cannot believe they were lost through code changes and noone noticed.

Ok, I found some suspicious locations. In some of them additional command line options are detected.

Code: Select all

$ grep -rHn NSProcessInfo *
src/Core/OXPVerifier/OOOXPVerifier.m:84:	arguments = [[NSProcessInfo processInfo] arguments];
src/Core/OOOpenALController.m:54:		arguments = [[NSProcessInfo processInfo] arguments];
src/Core/OOOpenGLExtensionManager.m:549:	NSArray 		*arguments = [[NSProcessInfo processInfo] arguments];
src/Core/OOLogHeader.m:156:		NSString *systemString = [NSString stringWithFormat:@OS_TYPE_STRING " %@", [[NSProcessInfo processInfo] operatingSystemVersionString]];
src/Core/OOLogHeader.m:188:		NSString *systemString = [NSString stringWithFormat:@OS_TYPE_STRING " %@", [[NSProcessInfo processInfo] operatingSystemVersionString]];
src/Core/Universe.m:10937:	arguments = [[NSProcessInfo processInfo] arguments];
src/Core/Entities/PlayerEntity.m:10001:		NSArray* arguments = [[NSProcessInfo processInfo] arguments];
src/Core/OOCPUInfo.m:85:	sNumberOfCPUs = [[NSProcessInfo processInfo] processorCount];
src/SDL/MyOpenGLView.m:178:	arguments = [[NSProcessInfo processInfo] arguments];
src/SDL/MyOpenGLView.m:2727:	NSArray* cmdline_arguments = [[NSProcessInfo processInfo] arguments];
$

That code is tricky! I would not even know where/how to document such distributed functionality.

[hiran]

The even more puzzling part is: what happened to all the other command line options?
https://wiki.alioth.net/index.php/Hidde ... parameters
I cannot believe they were documented but did not exist.
I also cannot believe they were lost through code changes and noone noticed.

Ok, I found some suspicious locations. In some of them additional command line options are detected.

Code: Select all

$ grep -rHn NSProcessInfo *
src/Core/OXPVerifier/OOOXPVerifier.m:84:	arguments = [[NSProcessInfo processInfo] arguments];
src/Core/OOOpenALController.m:54:		arguments = [[NSProcessInfo processInfo] arguments];
src/Core/OOOpenGLExtensionManager.m:549:	NSArray 		*arguments = [[NSProcessInfo processInfo] arguments];
src/Core/OOLogHeader.m:156:		NSString *systemString = [NSString stringWithFormat:@OS_TYPE_STRING " %@", [[NSProcessInfo processInfo] operatingSystemVersionString]];
src/Core/OOLogHeader.m:188:		NSString *systemString = [NSString stringWithFormat:@OS_TYPE_STRING " %@", [[NSProcessInfo processInfo] operatingSystemVersionString]];
src/Core/Universe.m:10937:	arguments = [[NSProcessInfo processInfo] arguments];
src/Core/Entities/PlayerEntity.m:10001:		NSArray* arguments = [[NSProcessInfo processInfo] arguments];
src/Core/OOCPUInfo.m:85:	sNumberOfCPUs = [[NSProcessInfo processInfo] processorCount];
src/SDL/MyOpenGLView.m:178:	arguments = [[NSProcessInfo processInfo] arguments];
src/SDL/MyOpenGLView.m:2727:	NSArray* cmdline_arguments = [[NSProcessInfo processInfo] arguments];
$

That code is tricky! I would not even know where/how to document such distributed functionality.

I did not like the fact that command line argument processing is distributed over so many classes/methods. Yet what can I do?
Then I found that Doxygen allows grouping some items into a special page, and that's what I did.

I defined a group 'cli' here:
- https://github.com/OoliteProject/oolite ... ro.dox#L65

Then I added relevant code pieces here:
- https://github.com/OoliteProject/oolite ... fier.m#L73
- https://github.com/OoliteProject/oolite ... ller.m#L46
- https://github.com/OoliteProject/oolite ... ger.m#L541
- https://github.com/OoliteProject/oolite ... e.m#L10928
- https://github.com/OoliteProject/oolite ... ty.m#L9943
- https://github.com/OoliteProject/oolite ... main.m#L53
- https://github.com/OoliteProject/oolite ... iew.m#L153
- https://github.com/OoliteProject/oolite ... main.m#L11

Doxygen's output for the group looks like this:
https://ooliteproject.github.io/oolite/group__cli.html

And I am surprised to see five group elements although I expected 8. Any idea what might prevent three of them from showing up?

[hiran]

When further looking at a developer's needs, somehow I feel doxygen is just not sufficient. Future developers would also have to guess how to setup their environment and make compilation/debugging work. Likely the choice of tools and procedures varies throughout the operating systems.

I may be guessing wrongly, but on the Apple Mac this was likely all handled by XCode.
What is required on Linux? What is required on Ubuntu? How is the code being developed and tested today?

Let's share/document whatever we know so we can build and maybe improve on it.