Add dox for FiletypeFuncs and some of GeanyFiletype.

Rename filetypes_detect_from_file() to
filetypes_detect_from_document().
Rename filetypes_detect_from_filename() to
filetypes_detect_from_file() because it also detects shebang lines.
Remove function prototype comments for filetypes.h (see filetypes.c
or API dox instead).


git-svn-id: https://geany.svn.sourceforge.net/svnroot/geany/trunk@2805 ea778897-0a13-0410-b9d1-a72fbfd435f5

ChangeLog

@@ -5,6 +5,15 @@
    Move utils_reload_configuration() to main.c.
  * src/main.c:
    Add doxygen file header for generating MainFuncs API documentation.
+ * src/plugindata.h, src/filetypes.c, src/filetypes.h, src/document.c,
+   src/plugins.c:
+   Add dox for FiletypeFuncs and some of GeanyFiletype.
+   Rename filetypes_detect_from_file() to
+   filetypes_detect_from_document().
+   Rename filetypes_detect_from_filename() to
+   filetypes_detect_from_file() because it also detects shebang lines.
+   Remove function prototype comments for filetypes.h (see filetypes.c
+   or API dox instead).
 
 
 2008-07-22  Enrico Tröger  <enrico(dot)troeger(at)uvena(dot)de>

src/document.c

@@ -572,7 +572,7 @@ GeanyDocument *document_new_file(const gchar *filename, GeanyFiletype *ft, const
 
 	/*document_set_filetype(idx, (ft == NULL) ? filetypes[GEANY_FILETYPES_NONE] : ft);*/
 	if (ft == NULL && filename != NULL) /* guess the filetype from the filename if one is given */
-		ft = filetypes_detect_from_file(doc);
+		ft = filetypes_detect_from_document(doc);
 
 	document_set_filetype(doc, ft);	/* also clears taglist */
 	if (ft == NULL)
@@ -1037,7 +1037,7 @@ GeanyDocument *document_open_file_full(GeanyDocument *doc, const gchar *filename
 		/* "the" SCI signal (connect after initial setup(i.e. adding text)) */
 		g_signal_connect(doc->editor->sci, "sci-notify", G_CALLBACK(on_editor_notification), doc);
 
-		use_ft = (ft != NULL) ? ft : filetypes_detect_from_file(doc);
+		use_ft = (ft != NULL) ? ft : filetypes_detect_from_document(doc);
 	}
 	else
 	{	/* reloading */
@@ -1260,7 +1260,7 @@ gboolean document_save_file_as(GeanyDocument *doc, const gchar *utf8_fname)
 	/* detect filetype */
 	if (FILETYPE_ID(doc->file_type) == GEANY_FILETYPES_NONE)
 	{
-		GeanyFiletype *ft = filetypes_detect_from_file(doc);
+		GeanyFiletype *ft = filetypes_detect_from_document(doc);
 
 		document_set_filetype(doc, ft);
 		if (document_get_current() == doc)

src/filetypes.c

@@ -21,7 +21,8 @@
  * $Id$
  */
 
-/*
+/**
+ * @file filetypes.h
  * Filetype detection, file extensions and filetype menu items.
  */
 
@@ -666,8 +667,8 @@ static GeanyFiletype *filetypes_detect_from_file_internal(const gchar *utf8_file
 }
 
 
-/* Detect the filetype for document idx. */
-GeanyFiletype *filetypes_detect_from_file(GeanyDocument *doc)
+/* Detect the filetype for the document, checking for a shebang, then filename extension. */
+GeanyFiletype *filetypes_detect_from_document(GeanyDocument *doc)
 {
 	GeanyFiletype *ft;
 	gchar *line;
@@ -682,9 +683,9 @@ GeanyFiletype *filetypes_detect_from_file(GeanyDocument *doc)
 }
 
 
-/* Detect filetype based on the filename extension.
- * utf8_filename can include the full path. */
-GeanyFiletype *filetypes_detect_from_filename(const gchar *utf8_filename)
+/** Detect filetype based on a shebang line in the file, or the filename extension. */
+/* Currently only used by external plugins. */
+GeanyFiletype *filetypes_detect_from_file(const gchar *utf8_filename)
 {
 	gchar line[1024];
 	FILE *f;

src/filetypes.h

@@ -29,7 +29,9 @@
 #include "ScintillaWidget.h"
 
 
-/* each group should be alpha-sorted, based on filetype::name (not enum name) */
+/* Each group should be alpha-sorted, based on filetype::name (not enum name).
+ * Warning: remember to break the plugin ABI when adding items (this enum needs to be changed
+ * to work with an ABI-stable filetype::group_name field. */
 typedef enum
 {
 	/* normally compiled languages */
@@ -103,15 +105,17 @@ struct build_programs
 	gboolean modified;
 };
 
+/** Represents a filetype. */
 struct GeanyFiletype
 {
-	filetype_id		  id;
-	langType 		  lang;				/* represents the langType of tagmanager(see the table */
-										/* in tagmanager/parsers.h), -1 represents all, -2 none */
-	gchar	 		 *name;				/* will be used as name for tagmanager */
-	gchar	 		 *title;			/* will be shown in the file open dialog */
-	gchar	 		 *extension;
-	gchar			**pattern;
+	filetype_id		  id;				/**< Index in @c filetypes_array. */
+	/** Represents the langType of tagmanager (see the table
+	 * in tagmanager/parsers.h), -1 represents all, -2 none. */
+	langType 		  lang;
+	gchar	 		 *name;				/**< Used as name for tagmanager. E.g. "C". */
+	gchar	 		 *title;			/**< Shown in the file open dialog. E.g. "C source file". */
+	gchar	 		 *extension;		/**< Default file extension for new files. */
+	gchar			**pattern;			/**< Array of filename-matching wildcard strings. */
 	gchar	 		 *context_action_cmd;
 	gchar	 		 *comment_open;
 	gchar	 		 *comment_close;
@@ -130,22 +134,16 @@ extern GPtrArray *filetypes_array;
 GeanyFiletype *filetypes_lookup_by_name(const gchar *name);
 
 
-/* Calls filetypes_init_types() and creates the filetype menu. */
 void filetypes_init(void);
 
-/* Create the filetype array and fill it with the known filetypes. */
 void filetypes_init_types(void);
 
-/* Detect the filetype for document idx, checking for a shebang, then filename extension. */
-GeanyFiletype *filetypes_detect_from_file(GeanyDocument *doc);
+GeanyFiletype *filetypes_detect_from_document(GeanyDocument *doc);
 
 GeanyFiletype *filetypes_detect_from_extension(const gchar *utf8_filename);
 
-/* Detect filetype based on the filename extension.
- * utf8_filename can include the full path. */
-GeanyFiletype *filetypes_detect_from_filename(const gchar *utf8_filename);
+GeanyFiletype *filetypes_detect_from_file(const gchar *utf8_filename);
 
-/* frees the array and all related pointers */
 void filetypes_free_types(void);
 
 void filetypes_load_config(gint ft_id, gboolean reload);

src/plugindata.h

@@ -36,7 +36,7 @@
 
 /* The API version should be incremented whenever any plugin data types below are
  * modified or appended to. */
-static const gint api_version = 80;
+static const gint api_version = 81;
 
 /* The ABI version should be incremented whenever existing fields in the plugin
  * data types below have to be changed or reordered. It should stay the same if fields

src/plugins.c

@@ -231,7 +231,7 @@ static HighlightingFuncs highlighting_funcs = {
 
 
 static FiletypeFuncs filetype_funcs = {
-	&filetypes_detect_from_filename,
+	&filetypes_detect_from_file,
 	&filetypes_lookup_by_name
 };