From 5e7b5fc44c3913c9a61b879054a82e8a8baf0653 Mon Sep 17 00:00:00 2001 From: AJ Kelly Date: Thu, 27 Oct 2011 18:22:08 -0500 Subject: [PATCH] documentation update --- Docs/CommandLineArgs.txt | 9 +++-- Docs/Devdocs/CodingStyle.txt | 48 ++++++++++++++++---------- Docs/Devdocs/GoldenRules.txt | 24 +++++-------- Docs/Devdocs/ezsockets.txt | 2 +- Docs/Devdocs/possible memory leaks.txt | 2 +- Docs/Devdocs/rivaldata.txt | 2 +- Docs/credits.txt | 25 +++++++------- 7 files changed, 58 insertions(+), 54 deletions(-) diff --git a/Docs/CommandLineArgs.txt b/Docs/CommandLineArgs.txt index da567dbfc6..e59b05aa3a 100644 --- a/Docs/CommandLineArgs.txt +++ b/Docs/CommandLineArgs.txt @@ -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 diff --git a/Docs/Devdocs/CodingStyle.txt b/Docs/Devdocs/CodingStyle.txt index 8888b85dae..b0e7885dca 100644 --- a/Docs/Devdocs/CodingStyle.txt +++ b/Docs/Devdocs/CodingStyle.txt @@ -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: diff --git a/Docs/Devdocs/GoldenRules.txt b/Docs/Devdocs/GoldenRules.txt index 3a6543ae3b..b9e4c8a179 100644 --- a/Docs/Devdocs/GoldenRules.txt +++ b/Docs/Devdocs/GoldenRules.txt @@ -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. \ No newline at end of file +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. \ No newline at end of file diff --git a/Docs/Devdocs/ezsockets.txt b/Docs/Devdocs/ezsockets.txt index fc7b455641..28a8e9fa14 100644 --- a/Docs/Devdocs/ezsockets.txt +++ b/Docs/Devdocs/ezsockets.txt @@ -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 diff --git a/Docs/Devdocs/possible memory leaks.txt b/Docs/Devdocs/possible memory leaks.txt index 18d4c8f61b..50e1dd8f8a 100644 --- a/Docs/Devdocs/possible memory leaks.txt +++ b/Docs/Devdocs/possible memory leaks.txt @@ -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 diff --git a/Docs/Devdocs/rivaldata.txt b/Docs/Devdocs/rivaldata.txt index 0fdcbb9a96..a6e04a787c 100644 --- a/Docs/Devdocs/rivaldata.txt +++ b/Docs/Devdocs/rivaldata.txt @@ -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 diff --git a/Docs/credits.txt b/Docs/credits.txt index 70058c6f24..d2f9dc8db7 100644 --- a/Docs/credits.txt +++ b/Docs/credits.txt @@ -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