Documentation for API

[tomf]

One of the things that makes KSP great is the  public API which allows al the great mods that exist to be created. However writing a mod is often a matter of trial and error trying to work out what each call on the API does and what the arguments mean

E.g. GameEvents EventData<float, ScienceSubject, ProtoVessel, bool> OnScienceRecieved - the community generated documentation hasn't been updated with the last two parameters and it is unclear what the last parameter means

Would it be possible to spend some time creating documentation for the API while creating 1.2

[Snark]

As a modder, I would really really really like to have documentation for the API.  So I totally feel your pain, here.

Unfortunately, API docs are a pretty tall order.  It's a super big work item, bigger than perhaps you realize.  Exactly how big I don't know, but having worked on commercial SDKs as a developer and collaborating closely with the technical writing staff, I'd hazard a guess that it would be at least as big as "occupy one Squad staff full-time for an entire patch release cycle", probably considerably bigger than that.

(Especially bearing in mind that Squad has never been in the business of documenting APIs.  Even the little documentation that's available out there is community-produced, as you point out.  So for them to document this themselves, they'd have to gear up to take on a new type of professional task that they don't have prior experience with, which makes this an even bigger ask.)

Given how incredibly busy Squad is doing things like fixing bugs, adding features, getting the next patch out the door, etc., I'm not sure that's the best use of their time.  Especially given that the community actually can produce documentation-- I'd rather have Squad staff working on the stuff that the community can't work on, i.e. game internals.

Now, what I would like to see would be a good community-driven wiki that documents the API.  The size of the modding community is considerably larger than the size of Squad itself, so this seems like the perfect kind of problem to community-source.  (And given how friendly and approachable the Squad devs are:  if the community built this and did most of the heavy lifting, I expect that it wouldn't be too to get input from the devs for the rough edges where users aren't sure how to document something.)

A wiki seems like the right answer. Preferably coupled with some automation that "initializes" the API by just reflecting all the public methods, members, and properties of the API and making "skeleton" pages for them all, with some facility for updating when new versions come out.  (And even that is a pretty tall order that would take a dedicated programmer a fair amount of time to implement.  Not everyone is set up to do that.  I could probably do it... but I don't have that kind of time.)

So, how about it, gang?  Community call to action?  Any takers?

Edited March 3, 2016 by Snark

[tomf]

I'm a developer myself and I know the pain of having to document after I have written all the code.

I'm not really a c# person, but I know that in Java when you compile a library you can choose whether variable/parameter names are left in the copiled code. Is that an option that could be enabled for this API? If so it could be quite easy to do and guessing the correct usage of GameEvents EventData<theScienceAmount, ScienceSubject, ProtoVessel, someMeaningfullName> OnScienceRecieved would be much easier and form a better starting point than we currently have.

[DMagic]

For that specific event the bool at the end is used to differentiate standard science transmissions/returns from the science lab and M700 resource scanner. Those two parts don't behave the same way when transmitting science so something in the event is needed to tell the two apart. The value is true for the science lab/M700 and false for all regular experiments. The protoVessel just lets you know which vessel the results came from.

[nightingale]

I think the biggest problem is that KSP doesn't really have a true public API.  Instead, we as modders have access to invoke pretty much anything in their code via the same internal API that Squad uses (ie. public class members, for those involved in the programming craft).  This gives us enormous flexibility in modding, but it means that trying to document that would be an absolutely massive undertaking.  I couldn't see a way in Visual Studio to count the number of classes that KSP has in 1.0.5, but by visual estimation its in the high hundreds, if not in the thousands.  Each class will have anywhere between three or four functions to over a hundred.  So documenting the whole thing (even if it wasn't a moving target) would easily mean looking at tens of thousands of different functions.

Obviously, that's not a viable approach.  So we probably need to narrow it down to the important ones.  But who decides what's important?  What's important to me (contract stuff, career stuff) doesn't intersect with what might be important to Thomas P. (Kopernicus dev).

This overwhelming effort could be why the previous API documentation failed (although I don't really know, and @The_Duck hasn't been seen on the forums in close to a year, so it's possible they simply lost interest in KSP). Although the idea of a wiki sounds appealing, I'd be inclined to say the approach should be to fork that (warning: there's no license specified anywhere on the documentation project).  The fork should be owned by an "organization" with multiple member in GitHub (so that it's not on one single person to deal with pull requests).  Then we have to get people to contribute (I know I'd be more willing to contribute if I know that pull requests would be accepted more than once a year)!

54 minutes ago, tomf said:

I'm not really a c# person, but I know that in Java when you compile a library you can choose whether variable/parameter names are left in the copiled code. Is that an option that could be enabled for this API? If so it could be quite easy to do and guessing the correct usage of GameEvents EventData<theScienceAmount, ScienceSubject, ProtoVessel, someMeaningfullName> OnScienceRecieved would be much easier and form a better starting point than we currently have.

This is the case for C# as well for public/protected members.  The problem is that the GameEvents.* accept a callback function, so the parameters don't actually get names.  I know a little about this one because the addition of the ProtoVessel was in 1.0, and the addition of the bool was in 1.0.1 (both broke Contract Configurator).  The hint as to what it is is from the 1.0.1 release notes:

Science contracts and science World Firsts can no longer be triggered with science gained by reverse engineering recovered vessels. You have to transmit or recover an actual experiment.

So the bool will be true if a vessel is being "reverse engineered", which it took me a long bit of experimenting to figure out is when KSP generates the list of experiments on the vessel for the vessel recovery dialog box.  The ProtoVessel parameter is the vessel the science is coming from and I assume was added in 1.0 to support those world firsts contracts in some way (not 100% sure how).

So yeah, you picked the perfect example to show the reason why getting this API documentation done as a community is both very difficult and very necessary.

EDIT: I'm al lot less sure of my answer after @DMagic's ninja - I think I'll have to do some verification as it may mean I have a bug or two in the handling of science labs.

EDIT2: Unstrikethrough.

Edited March 3, 2016 by nightingale

[DMagic]

@nightingale No, I think you are right. 

The bool that I was thinking of was one that was added to the Science Data object at some point in the last few updates.

[tomf]

Ok, it looks like the best that is going to happen is a restart of the community documentation project.

I have created an organisation on Github called KSP-API-docs and invited everyone who has contributed to this thread to join it. It would be great if one of the higher repped members would attempt to recruit people to make contributions.

I'll spend some time this morning adding in as many missing classes as I can find.

[nightingale]

5 hours ago, tomf said:

Ok, it looks like the best that is going to happen is a restart of the community documentation project.

I have created an organisation on Github called KSP-API-docs and invited everyone who has contributed to this thread to join it. It would be great if one of the higher repped members would attempt to recruit people to make contributions.

I'll spend some time this morning adding in as many missing classes as I can find.

Good stuff, although the one suggestion I would make is to hold off on the call to action for two weeks or so until the KSP 1.1 pre-release comes out - that will hopefully reduce the amount of re-work required from 1.1 changes (I don't imagine the changes between 1.1 pre-release and 1.1 full will be so significant to warrant waiting another two weeks on top of it).

[nightingale]

@tomf - can you go to the settings and enable the issue tracker?  I want to create a couple issue for stuff that needs to be done (one for manually pulling in the pending pull request on Anatid/XML-Documentation-for-the-KSP-API, and another to throw out some ideas I have to automate getting the info from the KSP dlls).

[The_Duck]

Hi guys-- sorry for abandoning the Github documentation project. I haven't spent time on KSP in quite a while. You're of course free to fork it. Let me know if you need explanations of how I built the XML and HTML docs from the .cs files.

[nightingale]

16 minutes ago, The_Duck said:

Hi guys-- sorry for abandoning the Github documentation project. I haven't spent time on KSP in quite a while. You're of course free to fork it. Let me know if you need explanations of how I built the XML and HTML docs from the .cs files.

Awesome, good to hear!  I'd like to put a license file on the fork - can you formally state a license for your original work to cover off any code/doxyfile/end-documentation?  If you don't know/care then I'd suggest MIT as a very simple and permissive license.

[nightingale]

I've added issue #2 to the GitHub with some suggestions on how we can improve the process going forward to make it easier for people to help out (by pre-generating all the class information so people just don't have to extract it themselves) and to make it easier to handle changes from one KSP version to another (by using a tool that handles the comparison and merges in a smart way automatically).  I'd like feedback from anyone who has some interest/expertise on that side of things.

[The_Duck]

On 3/4/2016 at 0:33 PM, nightingale said:

Awesome, good to hear!  I'd like to put a license file on the fork - can you formally state a license for your original work to cover off any code/doxyfile/end-documentation?  If you don't know/care then I'd suggest MIT as a very simple and permissive license.

Sure, I added a license.