Documentation Plan

If you wish to contribute to the Ace Attorney Online Game Creation Engine open source project, or just know more about the way it is developed, this is the place.

Moderator: EN - Forum Moderators

Post Reply
User avatar
Enthalpy
Community Manager
Posts: 5169
Joined: Wed Jan 04, 2012 4:40 am
Gender: Male
Spoken languages: English, limited Spanish

Documentation Plan

Post by Enthalpy »

A project as large as AAO needs documentation. This prompts the following questions:

* Where should the documentation go? The most obvious solution is to put documentation here and migrate it to the Wiki when it's available. However, the Wiki collapses all leading and trailing spaces, which could make formatting a pain.
* What information should the documentation cover?
* How should the documentation be formatted?
* How do we handle subjects where we don't know what the documentation should be? Functions like CE_updateEndFrame are self-explanatory, but the rowmaps system has be mystified even after playing around with the debugger, and I don't think running to Unas for every enigma can practically work.

Going question by question...

I'd favor putting this as a section in the Wiki, circumventing the space stripping by making heavy use of bullet points.
I want the documentation to cover the purpose of each function and method, at a minimum. I'd also like the meaning of all function arguments, return values, and a brief overview of procedure, except for short functions.
If formatting does use the bullet points, I envision something like this:

Generic Module
Purpose: To do generic things.
Init: None.

First Function
  • Purpose: Purpose of the function.
  • Arguments
    • Arg1: Gives generic information.
    • Arg2: Gives other generic information.
    Test
  • Procedure: Does generic stuff.


First Object
  • Methods
    • First Method
      • Purpose: To be even more generic.
      • Arguments: There's only one, but if there were two, they'd go onto the below line.


And etcetera.

How to handle the more complicated subjects to document, I have no idea.

Any other thoughts?
[D]isordered speech is not so much injury to the lips that give it forth, as to the disproportion and incoherence of things in themselves, so negligently expressed. ~ Ben Jonson
User avatar
Unas
Admin / Site programmer
Posts: 8850
Joined: Tue Jul 10, 2007 4:43 pm
Gender: Male
Spoken languages: Français, English, Español
Contact:

Re: Documentation Plan

Post by Unas »

The simplest thing would be for me to open the wiki directly, I guess :-P

Also, no, the documentation's purpose is not to explain the specific purpose of each single function.
If the purpose or working of a function is not obvious at first sight, it should be explained in a comment above the function itself in the code.

In Java, there is a standard syntax for these comments called JavaDoc, which allows generating an API documentation out of these. In JS there is a non-standard equivalent, JSDoc : I've never used it myself and I'm using just regular comments in AAO code, but if you wish to document the purpose of each single function the correct way to go is probably to update all my comments and add new ones using the JSDoc syntax.

The wiki is supposed to give a general overview of the project's architecture (How modules interact, etc.), and some entry points in the code for important features.
ImageImageImage
If knowledge can create problems, it is not through ignorance that we can solve them.
Si le savoir peut créer des problèmes, ce n'est pas l'ignorance qui les résoudra. ( Isaac Asimov )
User avatar
melelisun
Posts: 14
Joined: Sat Jul 07, 2012 4:46 am
Spoken languages: English, some Korean, some Japanese

Re: Documentation Plan

Post by melelisun »

Not sure if this would be helpful at all, but I've used the engine Ren'Py a lot and found its documentation really easy to navigate. It contains both a Quickstart guide as well as more detailed pages for each function with a list of descriptions / arguments.
User avatar
Enthalpy
Community Manager
Posts: 5169
Joined: Wed Jan 04, 2012 4:40 am
Gender: Male
Spoken languages: English, limited Spanish

Re: Documentation Plan

Post by Enthalpy »

I've gained a fair amount of programming experience since I started this topic, so I can better express now what was on my mind then:

The core problem is documenting the responsibilities of each module. It wasn't obvious to me at time of writing what "problem" each of the various modules solve. I could probably get a better idea now, but it would still take some doing.

I agree that documenting the arguments of individual functions is important, but that's relatively straightforward and should be done on an as-needed basis. It's documenting the purposes of modules that I think would be better served with dedicated effort.
[D]isordered speech is not so much injury to the lips that give it forth, as to the disproportion and incoherence of things in themselves, so negligently expressed. ~ Ben Jonson
Post Reply