more refractoring and documentation

nbproject/configurations.xml

           <in>dns_core.h</in>
           <in>item_effects.h</in>
           <in>items.h</in>
+          <in>memory.h</in>
           <in>oe_animation.h</in>
           <in>pkmn_attributes.h</in>
           <in>pokemon.h</in>
       </item>
       <item path="src/include/items.h" ex="false" tool="3" flavor2="0">
       </item>
+      <item path="src/include/memory.h" ex="false" tool="3" flavor2="0">
+      </item>
       <item path="src/include/oe_animation.h" ex="false" tool="3" flavor2="0">
       </item>
       <item path="src/include/pkmn_attributes.h" ex="false" tool="3" flavor2="0">

nbproject/private/configurations.xml

           <in>item_effects.h</in>
           <in>items.h</in>
           <in>lcd.h</in>
+          <in>memory.h</in>
           <in>moves.h</in>
           <in>objects.h</in>
           <in>oe_animation.h</in>

src/include/bpre.h

 void* memset (void* dst, int value, size_t size);
 
 //debug
-void agbprintf(const char* pBuf, ...);
+/*void agbprintf(const char* pBuf, ...);
 void agbprint_flush();
-void agb_assert(const char *file, int line, const char *expression, u32 stop);
+void agb_assert(const char *file, int line, const char *expression, u32 stop);*/
 
 // sound related stuff
-extern MPlayTable mplay_table[];
-extern SongTable _songtable[];
-void m4aSongNumStart(u16 songid);
-void MPlayStart_rev01(MusicPlayerArea *ma, SongHeader *so);
-void MPlayContinue(MusicPlayerArea *ma);
+
 
 //graphical stuff
 
 //object related stuff
-void objc_exec();
-void obj_sync();
+
 
 //task related stuff
-void task_exec();
+
 
 //attribute setter and getter
 u8 get_attributes(struct pokemon* poke_address, u8 request, void* destination);

src/include/callback.h

+/****************************************************************************
+ * Copyright (C) 2015-2016 by the SotS Team                                 *
+ *                                                                          *
+ * This file is part of Sovereign of the Skies.                             *
+ *                                                                          *
+ *   Sovereign of the Skies is free software: you can redistribute it       *
+ *   and/or modify it                                                       *
+ *   under the terms of the GNU Lesser General Public License as published  *
+ *   by the Free Software Foundation, either version 3 of the License, or   *
+ *   (at your option) any later version provided you include a copy of the  *
+ *   licence and this header.                                               *
+ *                                                                          *
+ *   Sovereign of the Skies is distributed in the hope that it will be      *
+ *   useful, but WITHOUT ANY WARRANTY; without even the implied warranty of *
+ *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the          *
+ *   GNU Lesser General Public License for more details.                    *
+ *                                                                          *
+ *   You should have received a copy of the GNU Lesser General Public       *
+ *   License along with Sovereign of the Skies.                             *
+ *   If not, see <http://www.gnu.org/licenses/>.                            *
+ ****************************************************************************/
+
+/**
+ * @file callback.h
+ * @author Sturmvogel
+ * @date 15 dec 2016
+ * @brief Manage callbacks and tasks
+ * 
+ * This header file provides methods to interact with callbacks and
+ * the task handler. It also defines the superstate structure,
+ * which contains callback information, sprite pointers, kesypad etc.
+ */
+
 #ifndef CALLBACK_H_
 #define CALLBACK_H_
 
 #include <objects.h>
+
+/* === TYPES === */
+
 typedef void (*callback)();
 
+/* === STRUCTURES === */
+
 struct int_superstate {
 	callback callback1;
 	callback callback2;
 	u8 multi_purpose_state_tracker;
 	u8 gpu_sprites_upload_skip;
  };
+
+/* === EXTERN STRUCTURES === */
  
 extern struct int_superstate superstate;
+
+/* === EXTERN METHODS === */
+
+/**
+ * @brief sets the second main callback
+ * @param address callback which should be set
+ */
 extern void set_callback2(callback address);
+
+/**
+ * @brief sets the vblank callback
+ * @param address callback which should be set
+ */
 extern void vblank_handler_set(callback address);
 
+/**
+ * @brief does everything the overworld needs to do
+ */
 extern void callback_overworld();
 
+/**
+ * @brief executes the task handler stack
+ */
+extern void task_exec();
+
 #endif

src/include/memory.h

+/****************************************************************************
+ * Copyright (C) 2015-2016 by the SotS Team                                 *
+ *                                                                          *
+ * This file is part of Sovereign of the Skies.                             *
+ *                                                                          *
+ *   Sovereign of the Skies is free software: you can redistribute it       *
+ *   and/or modify it                                                       *
+ *   under the terms of the GNU Lesser General Public License as published  *
+ *   by the Free Software Foundation, either version 3 of the License, or   *
+ *   (at your option) any later version provided you include a copy of the  *
+ *   licence and this header.                                               *
+ *                                                                          *
+ *   Sovereign of the Skies is distributed in the hope that it will be      *
+ *   useful, but WITHOUT ANY WARRANTY; without even the implied warranty of *
+ *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the          *
+ *   GNU Lesser General Public License for more details.                    *
+ *                                                                          *
+ *   You should have received a copy of the GNU Lesser General Public       *
+ *   License along with Sovereign of the Skies.                             *
+ *   If not, see <http://www.gnu.org/licenses/>.                            *
+ ****************************************************************************/
+
+/**
+ * @file memory.h
+ * @author Sturmvogel
+ * @date 15 dec 2016
+ * @brief Manage memory
+ * 
+ * This header file provides methods to allocate and free memory areas.
+ * It also provides basic memory copy/set methods.
+ */
+
+#ifndef MEMORY_H
+#define MEMORY_H
+
+/* === INCLUDE === */
+
+#include <types.h>
+
+/* === EXTERN METHODS === */
+
+/**
+ * @brief allocates memory
+ * @param size amount of bytes to allocate
+ * @return address to allocated memory area
+ */
+extern void* malloc(size_t size);
+
+/**
+ * @brief frees previously allocated memory
+ * @param address address to free
+ */
+extern void free(void* address);
+
+/**
+ * @brief copy bytes in memory
+ * @param destination address to copy to
+ * @param source address to copy from
+ * @param num amount of bytes to copy
+ * @return destination pointer
+ */
+extern void* memcpy (void * destination, const void* source, size_t num);
+
+/**
+ * @brief set bytes in memory
+ * @param dst destination to set words
+ * @param value to be set
+ * @param size number of bytes to set
+ * @return 
+ */
+extern void* memset (void* dst, int value, size_t size);
+
+#endif /* MEMORY_H */
+

src/include/objects.h

  *   GNU Lesser General Public License for more details.                    *
  *                                                                          *
  *   You should have received a copy of the GNU Lesser General Public       *
- *   License along with Box.  If not, see <http://www.gnu.org/licenses/>.   *
+ *   License along with Sovereign of the Skies.                             *
+ *   If not, see <http://www.gnu.org/licenses/>.                            *
  ****************************************************************************/
 
 /**
  */
 extern void obj_delete_all();
 
+/**
+ * @brief execute object callbacks
+ */
+extern void objc_exec();
+
+/**
+ * @brief synchronize object data with object hardware memory
+ */
+void obj_sync();
+
 
 #endif

src/include/sound.h

+/****************************************************************************
+ * Copyright (C) 2015-2016 by the SotS Team                                 *
+ *                                                                          *
+ * This file is part of Sovereign of the Skies.                             *
+ *                                                                          *
+ *   Sovereign of the Skies is free software: you can redistribute it       *
+ *   and/or modify it                                                       *
+ *   under the terms of the GNU Lesser General Public License as published  *
+ *   by the Free Software Foundation, either version 3 of the License, or   *
+ *   (at your option) any later version provided you include a copy of the  *
+ *   licence and this header.                                               *
+ *                                                                          *
+ *   Sovereign of the Skies is distributed in the hope that it will be      *
+ *   useful, but WITHOUT ANY WARRANTY; without even the implied warranty of *
+ *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the          *
+ *   GNU Lesser General Public License for more details.                    *
+ *                                                                          *
+ *   You should have received a copy of the GNU Lesser General Public       *
+ *   License along with Sovereign of the Skies.                             *
+ *   If not, see <http://www.gnu.org/licenses/>.                            *
+ ****************************************************************************/
+
+/**
+ * @file callback.h
+ * @author ipatix
+ * @date 15 dec 2016
+ * @brief Manage callbacks and tasks
+ * 
+ * This header file provides methods to interact with callbacks and
+ * the task handler. It also defines the superstate structure,
+ * which contains callback information, sprite pointers, kesypad etc.
+ */
+
 #ifndef SOUND_H_
 #define SOUND_H_
 
 #include "types.h"
 
-typedef struct MusicPlayerArea MusicPlayerArea;
-typedef struct MusicPlayerTrack MusicPlayerTrack;
-typedef struct SongHeader SongHeader;
+typedef struct music_player_area music_player_area;
+typedef struct music_player_track music_player_track;
+typedef struct song_header song_header;
 
 typedef struct {
-    MusicPlayerArea *ma;
-    MusicPlayerTrack *ta;
+    music_player_area *ma;
+    music_player_track *ta;
     u32 tn;
-} MPlayTable;
+} m_play_table;
 
 typedef struct {
-    SongHeader *so;
+    song_header *so;
     u16 ms, me;
-} SongTable;
+} song_table;
+
+extern m_play_table mplay_table[];
+extern song_table _songtable[];
+extern void m4aSongNumStart(u16 songid);
+extern void MPlayStart_rev01(music_player_area *ma, song_header *so);
+extern void MPlayContinue(music_player_area *ma);
 
 #endif

src/specials/custom_specials.c

 }
 
 static callback special_routines[5] = {
-	play_meteor,
+	met_play,
 	sp_move_camera,
 	init_script,
         some_test,

src/specials/cutscene_meteor.c

-#include "cutscene_meteor.h"
+/****************************************************************************
+ * Copyright (C) 2015-2016 by the SotS Team                                 *
+ *                                                                          *
+ * This file is part of Sovereign of the Skies.                             *
+ *                                                                          *
+ *   Sovereign of the Skies is free software: you can redistribute it       *
+ *   and/or modify it                                                       *
+ *   under the terms of the GNU Lesser General Public License as published  *
+ *   by the Free Software Foundation, either version 3 of the License, or   *
+ *   (at your option) any later version provided you include a copy of the  *
+ *   licence and this header.                                               *
+ *                                                                          *
+ *   Sovereign of the Skies is distributed in the hope that it will be      *
+ *   useful, but WITHOUT ANY WARRANTY; without even the implied warranty of *
+ *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the          *
+ *   GNU Lesser General Public License for more details.                    *
+ *                                                                          *
+ *   You should have received a copy of the GNU Lesser General Public       *
+ *   License along with Sovereign of the Skies.                             *
+ *   If not, see <http://www.gnu.org/licenses/>.                            *
+ ****************************************************************************/
+
+/**
+ * @file cutscene_meteor.c
+ * @author Sturmvogel
+ * @date 15 dec 2016
+ * @brief Cutscene to play "crashing meteor"
+ * 
+ * This source is able to play a cutscene, a meteor crashing on earth.
+ */
+
+/* === INCLUDES === */
+
+#include "../assets/meteor/met_background.h"
+#include "../assets/meteor/met_foreground.h"
+#include "../assets/meteor/met_sky.h"
+#include "../assets/meteor/met_meteor.h"
+#include "../assets/meteor/met_clouds.h"
+
+#include <callback.h>
+#include <lcd.h>
+#include <fade.h>
+#include <sound.h>
+#include <memory.h>
+
+/* === MACROS & DEFINES === */
 
 #define CLOUD_THROTTLE 4
 #define PALETTE_BG 0
 
 #define TAG_METEOR 0x2000
 
+/* === STRUCTURES === */
+
 struct meteor_memory{
 	void* bg_gfx;
 	void* bg_map;
 	u16 delay_end;
 };
 
+/* === PROTOTYPES === */
+
+/**
+ * @brief readies VRAM for our graphic setup
+ */
+void met_setup_vram();
+
+/**
+ * @brief callback for doing the actual animation
+ */
+void met_cutscene_cb();
+
+/**
+ * @brief callback to update the screen elements
+ */
+void met_update_screen();
+
+/**
+ * @brief callback for the meteor object entity
+ * @param self pointer to the meteor object entity
+ */
+void met_entity_cb(struct obj_entity* self);
+
+/**
+ * @brief finish the animation and free memory
+ */
+void met_free_end();
+
+/**
+ * @brief disable overworld scrolling in scrolling controller
+ */
+void met_setup_scrolling();
+
+/**
+ * @brief setup palettes for cutscene environment
+ */
+void met_setup_palettes();
+
+/* === STATIC ELEMENTS === */
+
+/*static memory block pointer for used structure*/
 static struct meteor_memory* memory = (struct meteor_memory*)(0x0203FFC0);
 
+/*oam attributes for the meteor object entity*/
 static struct obj_oam_attributes sprite_meteor = {0, 0x8000, 0x800, 0x0};
 
+/*frame list for the meteor object entity*/
 static struct obj_frame meteor_frames [4] = {
 	{0, 10},
 	{16, 10},
 	{0xFFFE, 0}
 };
 
+/*pointer to the frame list*/
 static struct obj_frame* meteor_frames_a [1] = {
 	meteor_frames
 };
 
+/*template for the meteor object entity*/
 static struct obj_template template_meteor = {
 	TAG_METEOR,
 	TAG_METEOR,
 	meteor_frames_a,
 	0,
 	(struct obj_rotscale_frame **) 0x08231CFC,
-	meteor_callback
+	met_entity_cb
 };
 
-void meteor_callback(struct obj_entity* self)
+void met_entity_cb(struct obj_entity* self)
 {
-	if(memory->meteor_moving > 0)
-	{
-		self->x--;
-		self->y++;
-		if(self->y > 130)
-		{
-			memory->meteor_moving = 0;
-			m4aSongNumStart(0xAB);
-		}
-
-	}
+    if(memory->meteor_moving > 0)
+    {
+        self->x--;
+        self->y++;
+        if(self->y > 130)
+        {
+            memory->meteor_moving = 0;
+            m4aSongNumStart(0xAB);
+        }
+    }
 }
 
-void play_meteor()
+void met_play()
 {
+        
 	memory->animate_clouds = 0;
 	memory->cloud_animation_state = 0;
 	memory-> meteor_moving = 0;
 	superstate.multi_purpose_state_tracker = 0;
-	vblank_handler_set(update_screen);
-	set_callback2(cutscene);
+	vblank_handler_set(met_update_screen);
+	set_callback2(met_cutscene_cb);
 }
-void cutscene()
+void met_cutscene_cb()
 {
 	if(superstate.multi_purpose_state_tracker == 0)
 	{
 	{
 		if((fade_controller.mix_color & 0x8000) == 0)
 		{
-			setup_vram();
+			met_setup_vram();
 			fade_screen(0xFFFFFFFF,0,0x10,0,0x0000);
 			memory->delay = 60*3;
 			memory->delay_end = 90;
 	else if(superstate.multi_purpose_state_tracker == 6)
 	{
 		if(memory->delay_end == 0)
-			end_playback();
+			met_free_end();
 		else
 			memory->delay_end--;
 	}
 		memory->cloud_animation_state=0;
 }
 
-void end_playback()
+void met_free_end()
 {
 	set_callback2(callback_overworld);
 	free(memory->bg_gfx);
 	free(memory->cloud_map);
 }
 
-void setup_scrolling()
+void met_setup_scrolling()
 {
 	lcd_io_set_func(0x14, 0x0);
 	lcd_io_set_func(0x16, 0x0);
 	lcd_io_set_func(0x1E, 0x0);
 }
 
-void setup_palettes()
+void met_setup_palettes()
 {
 	wram_decompress((void*)met_skyPal, palette_unfaded_buffer + PALETTE_SKY*32);
 	wram_decompress((void*)met_cloudsPal, palette_unfaded_buffer + PALETTE_CLOUD*32);
 	wram_decompress((void*)met_backgroundPal, palette_unfaded_buffer + PALETTE_BG*32);
 }
 
-void setup_vram()
+void met_setup_vram()
 {
 	gpu_tile_bg_drop_all_sets(0);
 	gpu_tile_bg_drop_all_sets(1);
 	gpu_bg_show(3);
 
 	gpu_sync_bg_visibility_and_mode();
-
-	setup_scrolling();
+	met_setup_scrolling();
 
 	//copy tilesets
 	memory->bg_gfx = malloc(0x40);
 	wram_decompress((void*)met_skyTiles, memory->sky_gfx);
 	gpu_copy_to_vram_by_bgid(3, memory->sky_gfx,0x7A0,0,1);
 
-
-
-
+        
 	//copy tilemaps
 	memory->bg_map = malloc(0x500);
 	wram_decompress((void*)met_backgroundMap, memory->bg_map);
 	wram_decompress((void*)met_skyMap, memory->sky_map);
 	gpu_copy_to_vram_by_bgid(3, memory->sky_map,0x500,0,2);
 
-
-	//copy palettes
-	//pal_decompress_slice_to_faded_and_unfaded((void*)met_skyPal, 16, 32);
-	//pal_decompress_slice_to_faded_and_unfaded((void*)met_foregroundPal, 48, 32);
-	//pal_decompress_slice_to_faded_and_unfaded((void*)met_cloudsPal, 32, 32);
-	setup_palettes();
+	met_setup_palettes();
 
 	//setup oam
 	obj_delete_all();
 	memory->animate_clouds = 1;
 }
 
-void update_screen()
+void met_update_screen()
 {
 	fade_update();
 	task_exec();

src/specials/cutscene_meteor.h

+/****************************************************************************
+ * Copyright (C) 2015-2016 by the SotS Team                                 *
+ *                                                                          *
+ * This file is part of Sovereign of the Skies.                             *
+ *                                                                          *
+ *   Sovereign of the Skies is free software: you can redistribute it       *
+ *   and/or modify it                                                       *
+ *   under the terms of the GNU Lesser General Public License as published  *
+ *   by the Free Software Foundation, either version 3 of the License, or   *
+ *   (at your option) any later version provided you include a copy of the  *
+ *   licence and this header.                                               *
+ *                                                                          *
+ *   Sovereign of the Skies is distributed in the hope that it will be      *
+ *   useful, but WITHOUT ANY WARRANTY; without even the implied warranty of *
+ *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the          *
+ *   GNU Lesser General Public License for more details.                    *
+ *                                                                          *
+ *   You should have received a copy of the GNU Lesser General Public       *
+ *   License along with Sovereign of the Skies.                             *
+ *   If not, see <http://www.gnu.org/licenses/>.                            *
+ ****************************************************************************/
+
 #ifndef CUTSCENE_METEOR_H_
 #define CUTSCENE_METEOR_H_
 
-#include "../assets/meteor/met_background.h"
-#include "../assets/meteor/met_foreground.h"
-#include "../assets/meteor/met_sky.h"
-#include "../assets/meteor/met_meteor.h"
-#include "../assets/meteor/met_clouds.h"
-#include <bpre.h>
-
-void play_meteor();
-void setup_vram();
-void cutscene();
-void update_screen();
-void meteor_callback(struct obj_entity* self);
-void end_playback();
+/**
+ * @brief initiates the animation
+ */
+void met_play();
 
 #endif