Restructure code, improve doxygen documentation

layer/layer-selector.c

@@ -424,9 +424,10 @@ static void layer_selector_clear_widgets(LayerSelector *self)
 }
 
 /**
- * @brief Check if specific layer number is present in list box
- * @param layer Layer nu,ber
- * @return TRUE if present
+ * @brief Check if a specific layer element with the given layer number is present in the layer selector
+ * @param self LayerSelector instance
+ * @param layer Layer number to check for
+ * @return TRUE if layer is present, else FALSE
  */
 static gboolean layer_selector_check_if_layer_widget_exists(LayerSelector *self, int layer) {
 	GList *list;
@@ -449,17 +450,30 @@ static gboolean layer_selector_check_if_layer_widget_exists(LayerSelector *self,
 	return ret;
 }
 
+/**
+ * @brief Setup the necessary drag and drop callbacks of layer elements.
+ * @param self LayerSelector instance. Used to get the DnD target entry.
+ * @param element LayerElement instance to set the callbacks
+ */
 static void sel_layer_element_setup_dnd_callbacks(LayerSelector *self, LayerElement *element)
 {
-	layer_element_set_dnd_callbacks(element, &self->dnd_target, 1,
-					sel_layer_element_drag_begin,
-					sel_layer_element_drag_data_get,
-					sel_layer_element_drag_end);
+	struct layer_element_dnd_data dnd_data;
+
+	if (!self || !element)
+		return;
+
+	dnd_data.entries = &self->dnd_target;
+	dnd_data.entry_count = 1;
+	dnd_data.drag_end = sel_layer_element_drag_end;
+	dnd_data.drag_begin = sel_layer_element_drag_begin;
+	dnd_data.drag_data_get = sel_layer_element_drag_data_get;
+
+	layer_element_set_dnd_callbacks(element, &dnd_data);
 }
 
 /**
- * @brief Analyze \p cell and append used layers to list box
- * @param listbox listbox to add layer
+ * @brief Analyze \p cell layers and append detected layers to layer selector \p self
+ * @param self LayerSelector instance
  * @param cell Cell to analyze
  */
 static void layer_selector_analyze_cell_layers(LayerSelector *self, struct gds_cell *cell)
@@ -557,8 +571,15 @@ static LayerElement *layer_selector_find_layer_element_in_list(GList *el_list, i
 }
 
 /**
- * @brief Load file and apply layer definitions to listbox
- * @param file_name CSV Layer Mapping File
+ * @brief Load the layer mapping from a CSV formatted file
+ *
+ * This function imports the layer specification from a file (see @ref lmf-spec).
+ * The layer ordering defined in the file is kept. All layers present in the
+ * current loaded library, which are not present in the layer mapping file
+ * are appended at the end of the layer selector list.
+ *
+ * @param self LayerSelector instance
+ * @param file_name File name to load from
  */
 static void layer_selector_load_layer_mapping_from_file(LayerSelector *self, gchar *file_name)
 {
@@ -658,9 +679,9 @@ static void layer_selector_load_mapping_clicked(GtkWidget *button, gpointer user
 
 
 /**
- * @brief Save layer mapping of whole list box into file
- * @param file_name layer mapping file
- * @param list_box listbox
+ * @brief Save layer mapping of selector \p self to a file
+ * @param self LayerSelector instance
+ * @param file_name File name to save to
  */
 static void layer_selector_save_layer_mapping_data(LayerSelector *self, const gchar *file_name)
 {

layer/layer-selector.h

@@ -48,39 +48,40 @@ enum layer_selector_sort_algo {LAYER_SELECTOR_SORT_DOWN = 0, LAYER_SELECTOR_SORT
 LayerSelector *layer_selector_new(GtkListBox *list_box);
 
 /**
- * @brief Generate layer widgets in \p listbox
+ * @brief Generate layer widgets in in the LayerSelector instance
  * @note This clears all previously inserted elements
- * @param listbox
+ * @param selector LayerSelector instance
  * @param libs The libraries to add
  */
 void layer_selector_generate_layer_widgets(LayerSelector *selector, GList *libs);
 
 /**
  * @brief Supply button for loading the layer mapping
- * @param button
- * @param main_window Parent window for dialogs
+ * @param selector LayerSelector instance
+ * @param button Load button. Will be referenced
+ * @param main_window Parent window for dialogs. Will be referenced
  */
 void layer_selector_set_load_mapping_button(LayerSelector *selector, GtkWidget *button, GtkWindow *main_window);
 
 /**
  * @brief Supply button for saving the layer mapping
- * @param button
- * @param main_window Parent window for dialogs
+ * @param selector LayerSelector instance
+ * @param button Save button. Will be refeneced
+ * @param main_window Parent window for dialogs. Will be referenced
  */
 void layer_selector_set_save_mapping_button(LayerSelector *selector, GtkWidget *button, GtkWindow *main_window);
 
 /**
- * @brief get the layer information present in the listbox of the selector
- * @return List with layer_info elements
+ * @brief Get a list of all layers that shall be exported when rendering the cells
+ * @param selector Layer selector instance
+ * @return List of layer_info structures containing the layer information
  */
 GList *layer_selector_export_rendered_layer_info(LayerSelector *selector);
 
 /**
- * @brief Force sorting of the layer selector in a specified way
- *
- * If the layer selector is not yet set up, this function has no effect.
- *
- * @param sort_function Sorting direction
+ * @brief Force the layer selector list to be sorted according to \p sort_function
+ * @param selector LayerSelector instance
+ * @param sort_function The sorting method (up or down sorting)
  */
 void layer_selector_force_sort(LayerSelector *selector, enum layer_selector_sort_algo sort_function);