documentation update

2011-10-27 18:22:08 -05:00
parent 1656e5a4c7
commit 5e7b5fc44c
7 changed files with 58 additions and 54 deletions
@@ -1,4 +1,4 @@
-sm-ssc Command Line Arguments
+StepMania 5 Command Line Arguments
 ================================================================================
 Pass all arguments with --. For example, version would be entered as --version.
 stepmania --version
@@ -9,9 +9,8 @@ stepmania moonlight.smzip
 [GameState]
 * player
 usage: --player=1
-Joins in the specified player. Can also pass --player=2 at the same time,
-if desired. However, sm-ssc does not support more than two players, so don't
-go past 2.
+Joins in the specified player. Can also pass --player=2 at the same time, if
+desired. However, SM5 does not support more than two players, so don't go past 2.

 * mode
 usage: --mode=
@@ -34,7 +33,7 @@ Exports strings for the installer.

 * ExportLuaInformation
 usage: --ExportLuaInformation
-Exports Lua.xml using the default theme (and anything it falls back on)
+Exports Lua.xml using the current theme (and anything it falls back on)
 for reference.

 * theme
@@ -1,35 +1,41 @@
-sm-ssc Code Style Guidelines
+sm-ssc/SM5 Code Style Guidelines
 --------------------------------------------------------------------------------
-AJ is biased, but prefers to edit text in SciTE and just uses Visual Studio when
-necessary. "It's really slow!"
-
-That being said, the sm-ssc code style guidelines are as follows:
+The sm-ssc/SM5 code style guidelines are as follows:

 1) Follow the current coding conventions set forth in the source code.
 This means use tabs. AJ prefers tabs have a width of 4. Visual Studio and web
-browsers assume tabs to be 8 by default. :/
-Use of the tab character means you can define however wide you want it to be.
+browsers assume tabs to be 8 by default.
+Use of the tab character means you can define however wide you want it to be
+within your editor's settings.

 Use of the space character is allowed for complex alignment. There are many
 examples of this in the code.

-If it can be done in one line, do so:
+If it can be done in one line (and it's in a header), do so:
 int xTwenty(int factor){ return factor*20; }

 Otherwise, follow what's in the code, namely...

 for single line ifs :
-if( somecrap )
+if( someCondition )
 	dosomethingelse();

+though lately, there has been a shift to
+if( someCondition )
+{
+	dosomethingelse();
+}
+for clarity and ease of expansion.
+
 for multi-lines:
-if( anothercrap )
+if( anotherCondition )
 {
 	omg();
 	lotsofstuff();
 }

-Naming conventions seem to be Hungarian (of Apps or System, I do not know).
+Variable naming conventions seem to be Hungarian, with m_ being used for
+class member variables.

 2) Remove any unnecessary whitespace. "Unnecessary" whitespace includes tabs
 at the end of } characters, tabs that lead nowhere, like this one:
@@ -38,20 +44,24 @@ and keep in mind that this can be done with spaces too:
    
 so watch yourself. Remove 'em all.

+With that in mind, it's best to use a space around () for clarity, as in the
+examples in #1 above.
+
 3) When making LOG->Trace()s in code, it's best to include the name of the Class
 and Function in [], like so:
 LOG->Info( "[NetworkSyncManager::Listen] Initializing socket..." );
-You may not always need to do this, but it helps for clarity and sanity.
+You may not always need to do this, but it's a good idea if you're logging a
+function with the same name in multiple classes.

-4) Comment style. (This is a preferred suggestion. You may choose to do whatever
+4) Comment style. (This is a preferred suggestion. You may use whatever style
 you like, but it is recommended to follow this style when submitting code for
 inclusion.)
 // is preferred for one-liners
 // and also blocks of text where the comment isn't too long.
-// sometimes you'll find // comments longer than this thrown in there by AJ
-/* instead of doing this.
- * when making a new line in a long form comment, start like this line.
- * and put the end where it fits. */
+
+/* when making a new line in a long form comment, it's preferred to start
+ * from the top line and also try to put the end mark as close to the end of
+ * the text as possible. */

 /*
 * doing this (first line blank) is discouraged, but is allowed in certain places.
@@ -60,7 +70,7 @@ inclusion.)
 * for consistency's sake.
 */
 
-/* use of long comments for one line is VERY discouraged */
+/* use of long comments for one line is discouraged (with exceptions) */
 // usually, it will will get cleaned up into this style, but there are exceptions:

 // exception #1: function arguments
@@ -71,7 +81,7 @@ void SomeFunction(size_t /*ACTUAL DATA TYPE*/)
 #define /* you must use long form in defines, */ \
 // otherwise it won't parse the newline correctly (this will cause an error) \

-// exception #3: .h files
+// (loose) exception #3: .h files
 /* ScreenTypicalExample - this always shows up like this. It usually is always one line, even when it extends past column 80. This is acceptible; Most people don't write novels here like I just did. */

 // on comment length:
@@ -1,23 +1,17 @@
-The Golden Rules of sm-ssc Development
+The Golden Rules of StepMania 5 Development
 --------------------------------------------------------------------------------
-In addition to CodingStyle.txt, this is the doctrine for operation of sm-ssc.
+In addition to CodingStyle.txt, this is the doctrine for operation of SM5.

-1) Always remember that the original branch of StepMania exists, and that we need
-to give back to it in order for sm-ssc to survive.
-(Literal: Be sure to commit useful changes/fixes to the mainline StepMania branch
-every so often.)
-
-2) If you want something done, you should probably work on it yourself. However,
+1) If you want something done, you should probably work on it yourself. However,
 SSC members should be willing to help if their area of expertise and the problem
 domain overlap (life permitting).

-3) Always know your priorities. sm-ssc is important, but it's not life itself.
-Take breaks every once in a while. Work on other things. Don't get burned out
-from nonstop sm-ssc development.
+2) Always know your priorities. StepMania is not your life.
+Take breaks every once in a while. Work on other things.
+Don't get burned out from nonstop development.

-4) Patches should be checked for compatibility/compilability before being
+3) Patches should be checked for compatibility/compilability before being
 accepted and integrated. Common sense, but a golden rule nevertheless.

-5) Anyone who decides to theme for sm-ssc during development is willing to
-accept that occasionally, changes to the default and/or fallback theme will
-break things.
+4) Anyone who decides to theme during development is willing to accept that
+occasionally, changes to the default and/or fallback theme will break things.
@@ -1,4 +1,4 @@
-HOW 2 UZE EZSOKETS BY FWEEM INC
+[How to Use EzSockets by freem]

 Hey there. ezsockets is the socket library used in StepMania. If you are going to
 develop any extended network functionality, it would be good to know about
@@ -1,5 +1,5 @@
 as found by cppcheck against normal sm4svn source (as of 20090527), so
-line numbers will be different in sm-ssc for some of these.
+line numbers will be different in SM5 for some of these.
 ==================================================================================
 [.\ActorFrameTexture.h:38]: (all) Memory leak: ActorFrameTexture::m_pRenderTarget

@@ -1,4 +1,4 @@
-okay what we should probabably do for rival data is fuck up stats somehow.
+Rival Data draft (old version)

 Here's what rival data should have, taken from Stats.xml

@@ -1,13 +1,17 @@
-sm-ssc credits (in no particular order)
---------------------------------------
-* "Programming" is used in regards to the sm-ssc project.
-* If you have any corrections to this list, let us know (via forums or IRC).
+StepMania 5 credits (in no particular order)
+--------------------------------------------
+If you have any corrections to this list, let us know (via forums or IRC).
+
+==StepMania Team==
+Chris Danford, Glenn Maynard, Steve Checkoway, et al
+ * Keeping StepMania 5 alive with changes, and providing a nice codebase for
+   us to work with.

 ==the spinal shark collective==
 AJ Kelly as freem
- * Project Coordinator/Leader
+ * (sm-ssc) Project Coordinator/Leader
 * Main programming
- * UserPreferences and some other Lua scripts
+ * Various Lua scripts
 * Some small theme edits here and there
 * Noteskins (retro, retrobar*)
 * Windows project file maintainer (mostly)
@@ -43,9 +47,10 @@ FSX

 Nicole Reid (okeeblow)
 * Tested building sm-ssc on FreeBSD, provided fixes.
+ (fixes that still need to get implemented)

 Thai Pangsakulyanont (theDtTvB)
- * Various changes to BMS support to make things work better.
+ * Changes to BMS loading/playback behavior to make things work better.

 Jason Felds (Wolfman2000)
 * [Player] PercentUntilColorCombo metric
@@ -53,11 +58,7 @@ Jason Felds (Wolfman2000)
 * Various fixes/changes. (see Changelogs for more details)

 ==other contributors==
-(in no particular order, aside from having SM team at the top)
-
-StepMania Team
- * Keeping StepMania 5 alive with changes, and providing a nice codebase for
-   us to work with.
+(in no particular order)

 1a2a3a2a1a
 * Various beat mode fixes