SF.net SVN: geany: [2263] trunk
eht16 at users.sourceforge.net
eht16 at xxxxx
Sun Feb 17 18:01:23 UTC 2008
Revision: 2263
http://geany.svn.sourceforge.net/geany/?rev=2263&view=rev
Author: eht16
Date: 2008-02-17 10:00:42 -0800 (Sun, 17 Feb 2008)
Log Message:
-----------
Add support for generating API reference documentation using doxygen.
This is the first step, it is far away from being complete.
Add make target "api-doc" to generate the reference documentation.
Add documentation comments to a few functions.
Move basic plugin documentation from plugindata.h to doc/plugins.dox.
Modified Paths:
--------------
trunk/ChangeLog
trunk/configure.in
trunk/doc/Makefile.am
trunk/src/dialogs.c
trunk/src/dialogs.h
trunk/src/document.c
trunk/src/document.h
trunk/src/encodings.c
trunk/src/encodings.h
trunk/src/plugindata.h
trunk/src/utils.c
trunk/src/utils.h
Added Paths:
-----------
trunk/doc/Doxyfile.in
trunk/doc/plugins.dox
Modified: trunk/ChangeLog
===================================================================
--- trunk/ChangeLog 2008-02-16 11:21:24 UTC (rev 2262)
+++ trunk/ChangeLog 2008-02-17 18:00:42 UTC (rev 2263)
@@ -1,3 +1,16 @@
+2008-02-17 Enrico Tröger <enrico(dot)troeger(at)uvena(dot)de>
+
+ * configure.in, doc/Doxyfile.in, doc/Makefile.am, doc/plugins.dox,
+ src/dialogs.c, src/dialogs.h, src/document.c, src/document.h,
+ src/encodings.c, src/encodings.h, src/plugindata.h, src/utils.c,
+ src/utils.h:
+ Add support for generating API reference documentation using doxygen.
+ This is the first step, it is far away from being complete.
+ Add make target "api-doc" to generate the reference documentation.
+ Add documentation comments to a few functions.
+ Move basic plugin documentation from plugindata.h to doc/plugins.dox.
+
+
2008-02-16 Enrico Tröger <enrico(dot)troeger(at)uvena(dot)de>
* doc/geany.html, doc/geany.txt:
Modified: trunk/configure.in
===================================================================
--- trunk/configure.in 2008-02-16 11:21:24 UTC (rev 2262)
+++ trunk/configure.in 2008-02-17 18:00:42 UTC (rev 2263)
@@ -232,6 +232,7 @@
doc/geany.1
geany.spec
geany.desktop.in
+doc/Doxyfile
])
echo "----------------------------------------"
Added: trunk/doc/Doxyfile.in
===================================================================
--- trunk/doc/Doxyfile.in (rev 0)
+++ trunk/doc/Doxyfile.in 2008-02-17 18:00:42 UTC (rev 2263)
@@ -0,0 +1,270 @@
+# Doxyfile 1.5.4
+
+#---------------------------------------------------------------------------
+# Project related configuration options
+#---------------------------------------------------------------------------
+DOXYFILE_ENCODING = UTF-8
+PROJECT_NAME = Geany
+PROJECT_NUMBER = @VERSION@
+OUTPUT_DIRECTORY = ./
+CREATE_SUBDIRS = NO
+OUTPUT_LANGUAGE = English
+BRIEF_MEMBER_DESC = YES
+REPEAT_BRIEF = YES
+ABBREVIATE_BRIEF = "The $name class " \
+ "The $name widget " \
+ "The $name file " \
+ is \
+ provides \
+ specifies \
+ contains \
+ represents \
+ a \
+ an \
+ the
+ALWAYS_DETAILED_SEC = NO
+INLINE_INHERITED_MEMB = NO
+FULL_PATH_NAMES = NO
+STRIP_FROM_PATH =
+STRIP_FROM_INC_PATH =
+SHORT_NAMES = NO
+JAVADOC_AUTOBRIEF = YES
+QT_AUTOBRIEF = NO
+MULTILINE_CPP_IS_BRIEF = NO
+DETAILS_AT_TOP = NO
+INHERIT_DOCS = YES
+SEPARATE_MEMBER_PAGES = NO
+TAB_SIZE = 4
+# ALIASES taken from pidgin
+ALIASES = "signal=- @ref " \
+ "signaldef=@subsection " \
+ "endsignaldef= " \
+ "signalproto=@code " \
+ "endsignalproto=@endcode " \
+ "signaldesc=@par Description: " \
+ "signals=@b Signals: " \
+ "endsignals= "
+OPTIMIZE_OUTPUT_FOR_C = YES
+OPTIMIZE_OUTPUT_JAVA = NO
+BUILTIN_STL_SUPPORT = NO
+CPP_CLI_SUPPORT = NO
+SIP_SUPPORT = NO
+DISTRIBUTE_GROUP_DOC = NO
+SUBGROUPING = YES
+TYPEDEF_HIDES_STRUCT = YES
+#---------------------------------------------------------------------------
+# Build related configuration options
+#---------------------------------------------------------------------------
+EXTRACT_ALL = NO
+EXTRACT_PRIVATE = NO
+EXTRACT_STATIC = NO
+EXTRACT_LOCAL_CLASSES = YES
+EXTRACT_LOCAL_METHODS = NO
+EXTRACT_ANON_NSPACES = NO
+HIDE_UNDOC_MEMBERS = YES
+HIDE_UNDOC_CLASSES = YES
+HIDE_FRIEND_COMPOUNDS = NO
+HIDE_IN_BODY_DOCS = YES
+INTERNAL_DOCS = NO
+CASE_SENSE_NAMES = YES
+HIDE_SCOPE_NAMES = NO
+SHOW_INCLUDE_FILES = NO
+INLINE_INFO = NO
+SORT_MEMBER_DOCS = YES
+SORT_BRIEF_DOCS = YES
+SORT_BY_SCOPE_NAME = NO
+GENERATE_TODOLIST = YES
+GENERATE_TESTLIST = NO
+GENERATE_BUGLIST = YES
+GENERATE_DEPRECATEDLIST= NO
+ENABLED_SECTIONS =
+MAX_INITIALIZER_LINES = 30
+SHOW_USED_FILES = NO
+SHOW_DIRECTORIES = NO
+FILE_VERSION_FILTER =
+#---------------------------------------------------------------------------
+# configuration options related to warning and progress messages
+#---------------------------------------------------------------------------
+QUIET = NO
+WARNINGS = YES
+WARN_IF_UNDOCUMENTED = YES
+WARN_IF_DOC_ERROR = YES
+WARN_NO_PARAMDOC = YES
+WARN_FORMAT = "$file:$line: $text "
+WARN_LOGFILE =
+#---------------------------------------------------------------------------
+# configuration options related to the input files
+#---------------------------------------------------------------------------
+INPUT = ../src/ ./
+INPUT_ENCODING = UTF-8
+FILE_PATTERNS = *.c \
+ *.cc \
+ *.cxx \
+ *.cpp \
+ *.c++ \
+ *.h \
+ *.hh \
+ *.hxx \
+ *.hpp \
+ *.h++ \
+ *.dox \
+ *.py \
+ *.C \
+ *.CC \
+ *.C++ \
+ *.H \
+ *.HH \
+ *.H++ \
+ *.dox \
+RECURSIVE = NO
+EXCLUDE =
+EXCLUDE_SYMLINKS = NO
+EXCLUDE_PATTERNS =
+EXCLUDE_SYMBOLS =
+EXAMPLE_PATH =
+EXAMPLE_PATTERNS = *
+EXAMPLE_RECURSIVE = NO
+IMAGE_PATH =
+INPUT_FILTER =
+FILTER_PATTERNS =
+FILTER_SOURCE_FILES = NO
+#---------------------------------------------------------------------------
+# configuration options related to source browsing
+#---------------------------------------------------------------------------
+SOURCE_BROWSER = NO
+INLINE_SOURCES = NO
+STRIP_CODE_COMMENTS = YES
+REFERENCED_BY_RELATION = NO
+REFERENCES_RELATION = NO
+REFERENCES_LINK_SOURCE = YES
+USE_HTAGS = NO
+VERBATIM_HEADERS = NO
+#---------------------------------------------------------------------------
+# configuration options related to the alphabetical class index
+#---------------------------------------------------------------------------
+ALPHABETICAL_INDEX = NO
+COLS_IN_ALPHA_INDEX = 5
+IGNORE_PREFIX =
+#---------------------------------------------------------------------------
+# configuration options related to the HTML output
+#---------------------------------------------------------------------------
+GENERATE_HTML = YES
+HTML_OUTPUT = reference/
+HTML_FILE_EXTENSION = .html
+HTML_HEADER =
+HTML_FOOTER =
+HTML_STYLESHEET =
+HTML_ALIGN_MEMBERS = YES
+GENERATE_HTMLHELP = NO
+HTML_DYNAMIC_SECTIONS = NO
+CHM_FILE =
+HHC_LOCATION =
+GENERATE_CHI = NO
+BINARY_TOC = NO
+TOC_EXPAND = NO
+DISABLE_INDEX = NO
+ENUM_VALUES_PER_LINE = 4
+GENERATE_TREEVIEW = NO
+TREEVIEW_WIDTH = 250
+#---------------------------------------------------------------------------
+# configuration options related to the LaTeX output
+#---------------------------------------------------------------------------
+GENERATE_LATEX = NO
+LATEX_OUTPUT = latex
+LATEX_CMD_NAME = latex
+MAKEINDEX_CMD_NAME = makeindex
+COMPACT_LATEX = NO
+PAPER_TYPE = a4wide
+EXTRA_PACKAGES =
+LATEX_HEADER =
+PDF_HYPERLINKS = NO
+USE_PDFLATEX = NO
+LATEX_BATCHMODE = NO
+LATEX_HIDE_INDICES = NO
+#---------------------------------------------------------------------------
+# configuration options related to the RTF output
+#---------------------------------------------------------------------------
+GENERATE_RTF = NO
+RTF_OUTPUT = rtf
+COMPACT_RTF = NO
+RTF_HYPERLINKS = NO
+RTF_STYLESHEET_FILE =
+RTF_EXTENSIONS_FILE =
+#---------------------------------------------------------------------------
+# configuration options related to the man page output
+#---------------------------------------------------------------------------
+GENERATE_MAN = NO
+MAN_OUTPUT = man
+MAN_EXTENSION = .3
+MAN_LINKS = NO
+#---------------------------------------------------------------------------
+# configuration options related to the XML output
+#---------------------------------------------------------------------------
+GENERATE_XML = NO
+XML_OUTPUT = xml
+XML_SCHEMA =
+XML_DTD =
+XML_PROGRAMLISTING = YES
+#---------------------------------------------------------------------------
+# configuration options for the AutoGen Definitions output
+#---------------------------------------------------------------------------
+GENERATE_AUTOGEN_DEF = NO
+#---------------------------------------------------------------------------
+# configuration options related to the Perl module output
+#---------------------------------------------------------------------------
+GENERATE_PERLMOD = NO
+PERLMOD_LATEX = NO
+PERLMOD_PRETTY = YES
+PERLMOD_MAKEVAR_PREFIX =
+#---------------------------------------------------------------------------
+# Configuration options related to the preprocessor
+#---------------------------------------------------------------------------
+ENABLE_PREPROCESSING = YES
+MACRO_EXPANSION = YES
+EXPAND_ONLY_PREDEF = YES
+SEARCH_INCLUDES = NO
+INCLUDE_PATH =
+INCLUDE_FILE_PATTERNS =
+# make G_GNUC_PRINTF a no-op unless doxygen would ignore functions with varargs
+PREDEFINED = "G_GNUC_PRINTF(x,y)="
+EXPAND_AS_DEFINED =
+SKIP_FUNCTION_MACROS = NO
+#---------------------------------------------------------------------------
+# Configuration::additions related to external references
+#---------------------------------------------------------------------------
+TAGFILES =
+GENERATE_TAGFILE =
+ALLEXTERNALS = NO
+EXTERNAL_GROUPS = YES
+PERL_PATH = /usr/bin/perl
+#---------------------------------------------------------------------------
+# Configuration options related to the dot tool
+#---------------------------------------------------------------------------
+CLASS_DIAGRAMS = NO
+MSCGEN_PATH =
+HIDE_UNDOC_RELATIONS = YES
+HAVE_DOT = NO
+CLASS_GRAPH = YES
+COLLABORATION_GRAPH = YES
+GROUP_GRAPHS = YES
+UML_LOOK = NO
+TEMPLATE_RELATIONS = NO
+INCLUDE_GRAPH = YES
+INCLUDED_BY_GRAPH = YES
+CALL_GRAPH = NO
+CALLER_GRAPH = NO
+GRAPHICAL_HIERARCHY = YES
+DIRECTORY_GRAPH = YES
+DOT_IMAGE_FORMAT = png
+DOT_PATH =
+DOTFILE_DIRS =
+DOT_GRAPH_MAX_NODES = 50
+MAX_DOT_GRAPH_DEPTH = 1000
+DOT_TRANSPARENT = YES
+DOT_MULTI_TARGETS = NO
+GENERATE_LEGEND = YES
+DOT_CLEANUP = YES
+#---------------------------------------------------------------------------
+# Configuration::additions related to the search engine
+#---------------------------------------------------------------------------
+SEARCHENGINE = NO
Property changes on: trunk/doc/Doxyfile.in
___________________________________________________________________
Name: svn:keywords
+ Author Date Id Revision
Name: svn:eol-style
+ native
Modified: trunk/doc/Makefile.am
===================================================================
--- trunk/doc/Makefile.am 2008-02-16 11:21:24 UTC (rev 2262)
+++ trunk/doc/Makefile.am 2008-02-17 18:00:42 UTC (rev 2263)
@@ -1,7 +1,7 @@
man_MANS=geany.1
DOCDIR = $(DESTDIR)/$(datadir)/doc/@PACKAGE@
IMAGE_FILES = images/*.png
-EXTRA_DIST = geany.html geany.css geany.txt geany.1 \
+EXTRA_DIST = geany.html geany.css geany.txt geany.1 plugins.dox \
$(srcdir)/$(IMAGE_FILES)
pdf: geany.txt
@@ -10,6 +10,9 @@
rm -f geany.tex geany.aux geany.log geany.out
mv $(srcdir)/geany.pdf geany-$(VERSION).pdf
+api-doc: Doxyfile
+ doxygen >/dev/null
+
doc: geany.txt
rst2html -stg --stylesheet=geany.css $(srcdir)/geany.txt geany.html
Added: trunk/doc/plugins.dox
===================================================================
--- trunk/doc/plugins.dox (rev 0)
+++ trunk/doc/plugins.dox 2008-02-17 18:00:42 UTC (rev 2263)
@@ -0,0 +1,266 @@
+/*
+ * plugins.dox - this file is part of Geany, a fast and lightweight IDE
+ *
+ * Copyright 2008 Enrico Tröger <enrico(dot)troeger(at)uvena(dot)de>
+ * Copyright 2008 Nick Treleaven <nick(dot)treleaven(at)btinternet(dot)com>
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program 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 General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
+ * MA 02110-1301, USA.
+ *
+ * $Id$
+ *
+ * This file contains additional plugin documentation like the signal system and a small howto.
+ * It is best viewed when filetype is set to C or C++.
+ */
+
+
+/**
+ *
+ * @mainpage Geany Plugin API Documentation
+ *
+ * @author Enrico Tröger, Nick Treleaven
+ * @date $Date$
+ *
+ * @section Intro
+ * This is the Geany API documentation. It is far from being complete and should be
+ * considered as a work in progress.
+ * We will try to %document as many functions and structs as possible.
+ *
+ * For additional documentation of things like plugin signals or a simple plugin please
+ * see Related Pages.
+ *
+ *
+ *
+ * @page symbols Plugin Symbols
+ *
+ * The following symbols (functions) should be exported by every plugin. Some of them
+ * are optional, i.e. they can be omitted, others are required and must be defined.
+ *
+ * - @code version_check() @endcode
+ * Use VERSION_CHECK() macro instead. Required by Geany.
+ *
+ * - @code PluginInfo* info() @endcode
+ * Use PLUGIN_INFO() macro to define it. Required by Geany.
+ *
+ * - @code GeanyData* geany_data @endcode
+ * Geany owned fields and functions.
+ *
+ * - @code PluginFields* plugin_fields @endcode
+ * Plugin owned fields, including flags.
+ *
+ * - @code GeanyCallback geany_callbacks[] @endcode
+ * An array for connecting GeanyObject events, which should be terminated with
+ * {NULL, NULL, FALSE, NULL}. See @link signals Signal documentation @endlink.
+ *
+ * - @code void configure(GtkWidget *parent) @endcode
+ * Called when the plugin should show a configure dialog to let the user set some basic
+ * plugin configuration. Optionally, can be omitted when not needed.
+ *
+ * - @code void init(GeanyData *data) @endcode
+ * Called after loading the plugin. data is the same as geany_data.
+ *
+ * - @code void cleanup() @endcode
+ * Called before unloading the plugin. Required for normal plugins - it should undo
+ * everything done in init() - e.g. destroy menu items, free memory.
+ *
+ *
+ *
+ * @page signals Plugin Signals
+ *
+ *
+ * @section Usage
+ *
+ * To use plugin signals in Geany, you simply create a GeanyCallback array, list the signals
+ * you want to listen to and create the appropiate signal callbacks for each signal.
+ * @note The GeanyCallback array has be ended with a final NULL entry.
+ *
+ * The following code demonstrates how to use signals in Geany plugins. The code can be inserted
+ * in your plugin code at any desired position.
+ *
+ * @code
+static void on_document_open(GObject *obj, gint idx, gpointer user_data)
+{
+ printf("Example: %s was opened\n", DOC_FILENAME(idx));
+}
+
+GeanyCallback geany_callbacks[] =
+{
+ { "document-open", (GCallback) &on_document_open, FALSE, NULL },
+ { NULL, NULL, FALSE, NULL }
+};
+ * @endcode
+ *
+ * @section Signals
+ *
+ * @signaldef document-new
+ * @signalproto
+ * void user_function(GObject *obj, gint idx, gpointer user_data);
+ * @endsignalproto
+ * @signaldesc
+ * Sent when a new %document is created.
+ * @param obj a GeanyObject instance, should be ignored.
+ * @param idx the index of the new %document.
+ * @param user_data user data.
+ * @endsignaldef
+ *
+ * @signaldef document-open
+ * @signalproto
+ * void user_function(GObject *obj, gint idx, gpointer user_data);
+ * @endsignalproto
+ * @signaldesc
+ * Sent when a new %document is opened.
+ * @param obj a GeanyObject instance, should be ignored.
+ * @param idx the index of the opened %document.
+ * @param user_data user data.
+ * @endsignaldef
+ *
+ * @signaldef document-save
+ * @signalproto
+ * void user_function(GObject *obj, gint idx, gpointer user_data);
+ * @endsignalproto
+ * @signaldesc
+ * Sent when a new %document is saved.
+ * @param obj a GeanyObject instance, should be ignored.
+ * @param idx the index of the saved %document.
+ * @param user_data user data.
+ * @endsignaldef
+ *
+ * @signaldef document-activate
+ * @signalproto
+ * void user_function(GObject *obj, gint idx, gpointer user_data);
+ * @endsignalproto
+ * @signaldesc
+ * Sent when switching notebook pages.
+ * @param obj a GeanyObject instance, should be ignored.
+ * @param idx the index of the new %document.
+ * @param user_data user data.
+ * @endsignaldef
+ *
+ * @signaldef project-open
+ * @signalproto
+ * void user_function(GObject *obj, GKeyFile *config, gpointer user_data);
+ * @endsignalproto
+ * @signaldesc
+ * Sent after a project is opened but before session files are loaded.
+ * @param obj a GeanyObject instance, should be ignored.
+ * @param config an exising GKeyFile object which can be used to read and write data.
+ * It must not be closed or freed.
+ * @param user_data user data.
+ * @endsignaldef
+ *
+ * @signaldef project-save
+ * @signalproto
+ * void user_function(GObject *obj, GKeyFile *config, gpointer user_data);
+ * @endsignalproto
+ * @signaldesc
+ * Sent when a project is saved(happens when the project is created, the properties
+ * dialog is closed or Geany is exited). This signal is emitted shortly before Geany
+ * will write the contents of the GKeyFile to the disc.
+ * @param obj a GeanyObject instance, should be ignored.
+ * @param config an exising GKeyFile object which can be used to read and write data.
+ * It must not be closed or freed.
+ * @param user_data user data.
+ * @endsignaldef
+ *
+ * @signaldef project-close
+ * @signalproto
+ * void user_function(GObject *obj, GKeyFile *config, gpointer user_data);
+ * @endsignalproto
+ * @signaldesc
+ * Sent after a project is closed.
+ * @param obj a GeanyObject instance, should be ignored.
+ * @param config an exising GKeyFile object which can be used to read and write data.
+ * It must not be closed or freed.
+ * @param user_data user data.
+ * @endsignaldef
+ *
+ *
+ *
+ * @page howto Plugin Howto
+ *
+ * @section intro Introduction
+ *
+ * Since Geany 0.12 there is a plugin interface to extend Geany's functionality and
+ * add new features. This %document gives a briefly overview about how to add new
+ * plugins by writing a simple "Hello World" plugin in C.
+ *
+ *
+ * @section start Getting started
+ *
+ * @subsection structure Plugin structure
+ *
+ * Every plugin must contain some essential symbols unless it won't work. A complete
+ * list of all necessary and optional symbols can be found in
+ * @link symbols Plugin Symbols @endlink.
+ * Every plugin should include "geany.h" and "plugindata.h" which provide necessary
+ * preprocessor macros and other basic information.
+ * There are two important preprocessor macros which need to be used at the beginning:
+ * PLUGIN_INFO() and VERSION_CHECK().
+ *
+ * PLUGIN_INFO() tells Geany about basic plugin information like name, description,
+ * version and author of the plugin.
+ *
+ * VERSION_CHECK() checks for compatibility of the API version which the plugin uses with
+ * the used Geany sources. Furthermore, it also checks the binary compatiblity of the plugin
+ * with Geany.
+ *
+ * A few functions are necessary to let Geany work with the plugin, at least init() must
+ * exist in the plugin. cleanup() should also be used to free allocated memory or destroy
+ * created widgets.
+ *
+ * @subsection buildenv Build environment
+ *
+ * To be able to write plugins for Geany, you need the source code and some development
+ * packages for GTK and its dependencies. I will only describe the way to compile and
+ * build plugins on Unix-like systems [1].
+ * If you already have the Geany source code and compiled it from them, you can skip the
+ * following.
+ *
+ * First you need to get the source code of Geany from the website at
+ * http://geany.uvena.de/Download/Releases [2]. Then install the development files for GTK
+ * and its dependencies. The easiest way to do this is to use your distribution's package
+ * management system, e.g. on Debian and Ubuntu systems you can use
+ * @code apt-get install libgtk2.0-dev intltool @endcode
+ * This will install all necessary files to be able to compile Geany and plugins. On other
+ * distributions, the package names and commands to use may differ.
+ *
+ * Basically, we are done at this point and could continue with writing the plugin code.
+ * You don't need necessarily to configure and build the Geany sources when the sources
+ * have the same version as your running Geany installation. But if the version of the
+ * sources differ from your Geany installation or especially when you used the source code
+ * from the Subversion repository, we strongly recommend to configure and build these
+ * sources and use it. To do so, run @code
+ ./configure && make
+ su -c "make install"
+ * @endcode
+ * in your Geany source directory. This will build and install Geany on your system.
+ *
+ * [1] For Windows, it is basically the same but you might have some more work on setting up
+ * the general build environment(compiler, GTK development files, ...). This is described on
+ * Geany's website at http://geany.uvena.de/Support/BuildingOnWin32.
+ *
+ * [2] You can also use the bleedging edge source code from our Subversion repository.
+ * More information about this can be found at http://geany.uvena.de/Download/SVN.
+ *
+ * @section helloworld "Hello World"
+ *
+ * We want to write a really simple "Hello World" plugin which opens a message dialog
+ * and just prints "Hello World".
+ *
+ *
+ * ... to be continued ...
+ *
+ *
+ **/
Property changes on: trunk/doc/plugins.dox
___________________________________________________________________
Name: svn:keywords
+ Author Date Id Revision
Name: svn:eol-style
+ native
Modified: trunk/src/dialogs.c
===================================================================
--- trunk/src/dialogs.c 2008-02-16 11:21:24 UTC (rev 2262)
+++ trunk/src/dialogs.c 2008-02-17 18:00:42 UTC (rev 2263)
@@ -581,8 +581,11 @@
#endif
-/* Show the Save As dialog for the current notebook page.
- * Returns: TRUE if the file was saved. */
+/**
+ * Show the Save As dialog for the current notebook page.
+ *
+ * @return @a TRUE if the file was saved, otherwise @a FALSE.
+ **/
gboolean dialogs_show_save_as()
{
gboolean result;
@@ -607,6 +610,16 @@
}
+/**
+ * Show a message box of the type @c type with @c text.
+ * On Unix-like systems a GTK message dialog box is shown, on Win32 systems a native Windows
+ * message dialog box is shown.
+ *
+ * @param type A GtkMessageType, can be one of: GTK_MESSAGE_INFO, GTK_MESSAGE_WARNING,
+ * GTK_MESSAGE_QUESTION, GTK_MESSAGE_ERROR
+ * @param text Printf()-style format string.
+ * @param ... Arguments for the @c text format string.
+ **/
void dialogs_show_msgbox(gint type, const gchar *text, ...)
{
#ifndef G_OS_WIN32
@@ -1300,7 +1313,7 @@
static gboolean show_question(GtkWidget *parent, const gchar *yes_btn, const gchar *no_btn,
- const gchar *question_text, const gchar *extra_text)
+ const gchar *question_text, const gchar *extra_text)
{
gboolean ret = FALSE;
#ifdef G_OS_WIN32
@@ -1337,6 +1350,16 @@
}
+/**
+ * Show a question message box with @c text and Yes/No buttons.
+ * On Unix-like systems a GTK message dialog box is shown, on Win32 systems a native Windows
+ * message dialog box is shown.
+ *
+ * @param text Printf()-style format string.
+ * @param ... Arguments for the @c text format string.
+ *
+ * @return @a TRUE if the user answered with Yes, otherwise @a FALSE.
+ **/
gboolean dialogs_show_question(const gchar *text, ...)
{
gboolean ret = FALSE;
Modified: trunk/src/dialogs.h
===================================================================
--- trunk/src/dialogs.h 2008-02-16 11:21:24 UTC (rev 2262)
+++ trunk/src/dialogs.h 2008-02-17 18:00:42 UTC (rev 2263)
@@ -21,7 +21,12 @@
* $Id$
*/
+/**
+ * @file dialogs.h
+ * File related dialogs, miscellaneous dialogs, font dialog.
+ **/
+
#ifndef GEANY_DIALOGS_H
#define GEANY_DIALOGS_H 1
Modified: trunk/src/document.c
===================================================================
--- trunk/src/document.c 2008-02-16 11:21:24 UTC (rev 2262)
+++ trunk/src/document.c 2008-02-17 18:00:42 UTC (rev 2263)
@@ -22,8 +22,8 @@
*/
/*
- * Document related actions: new, save, open, etc.
- * Also Scintilla search actions.
+ * Document related actions: new, save, open, etc.
+ * Also Scintilla search actions.
*/
#include "geany.h"
@@ -121,10 +121,17 @@
}
-/* filename is in UTF-8 for non-TagManager filenames.
- * is_tm_filename should only be used when passing a TagManager filename,
- * which is therefore locale-encoded and already a realpath().
- * Returns: the document index which has the given filename. */
+/**
+ * Find and retrieve the index of the given filename @a filename in the %document list.
+ *
+ * @param filename The filename to search (in UTF-8 encoding for non-TagManager filenames,
+ * else in locale encoding).
+ * @param is_tm_filename Whether the passed @a filename is a TagManager filename and therefore
+ * locale-encoded and already a realpath().
+ *
+ * @return The %document index which has the given filename @a filename or @c -1
+ * if @a filename is not open.
+ **/
gint document_find_by_filename(const gchar *filename, gboolean is_tm_filename)
{
guint i;
@@ -187,7 +194,14 @@
}
-/* returns the index of the given notebook page in the document list */
+/**
+ * Find and retrieve the index of the given notebook page @a page_num in the %document list.
+ *
+ * @param page_num The notebook page number to search.
+ *
+ * @return The index of the given notebook page @a page_num in the %document list or @c -1
+ * if no documents are opened.
+ **/
gint document_get_n_idx(guint page_num)
{
ScintillaObject *sci;
@@ -200,7 +214,12 @@
}
-/* returns the index of the current notebook page in the document list */
+/**
+ * Find and retrieve the index of the current %document.
+ *
+ * @return The index of the current notebook page in the %document list or @c -1
+ * if no documents are opened.
+ **/
gint document_get_cur_idx()
{
gint cur_page = gtk_notebook_get_current_page(GTK_NOTEBOOK(app->notebook));
@@ -217,7 +236,11 @@
}
-/* returns NULL if no documents are open */
+/**
+ * Find and retrieve the current %document.
+ *
+ * @return A pointer to the current %document or @c NULL if there are no opened documents.
+ **/
document *document_get_current()
{
gint idx = document_get_cur_idx();
@@ -238,6 +261,13 @@
}
+/**
+ * Update the tab labels, the status bar, the window title and some save-sensitive buttons
+ * according to the document's save state.
+ * This is called by Geany mostly when opening or saving files.
+ *
+ * @param idx The %document index to operate on.
+ **/
void document_set_text_changed(gint idx)
{
if (DOC_IDX_VALID(idx) && ! main_status.quitting)
@@ -478,7 +508,14 @@
}
-/* removes the given notebook tab and clears the related entry in the document list */
+/**
+ * Remove the given notebook tab at @a page_num and clear all related information
+ * in the document list.
+ *
+ * @param page_num The notebook page number to remove.
+ *
+ * @return @a TRUE if the document was actually removed or @a FALSE otherwise.
+ **/
gboolean document_remove(guint page_num)
{
gint idx = document_get_n_idx(page_num);
@@ -516,7 +553,11 @@
build_menu_update(-1);
}
}
- else geany_debug("Error: idx: %d page_num: %d", idx, page_num);
+ else
+ {
+ geany_debug("Error: idx: %d page_num: %d", idx, page_num);
+ return FALSE;
+ }
return TRUE;
}
@@ -531,12 +572,16 @@
}
-/* Create a new document.
- * filename is either the UTF-8 file name, or NULL.
- * If ft is NULL and filename is not NULL, then the filetype will be guessed
- * from the given filename.
- * text is the contents of the new file in valid UTF-8 encoding, or NULL.
- * Returns: idx of new file in doc_list. */
+/**
+ * Creates a new %document.
+ * After all, the "document-new" signal is emitted for plugins.
+ *
+ * @param filename The file name in UTF-8 encoding, or @c NULL to open a file as "untitled".
+ * @param ft The filetype to set or @c NULL to detect it from @a filename if not @c NULL.
+ * @param text The initial content of the file (in UTF-8 encoding), or @c NULL.
+ *
+ * @return The index of the new file in the @ref doc_list array.
+ **/
gint document_new_file(const gchar *filename, filetype *ft, const gchar *text)
{
gint idx = document_create_new_sci(filename);
@@ -597,11 +642,30 @@
}
-/* This is a wrapper for document_open_file_full(), see that function for details.
- * Do not use this when opening multiple files (unless using document_delay_colourise()). */
+/**
+ * Open a %document specified by @a locale_filename.
+ * After all, the "document-open" signal is emitted for plugins.
+ *
+ * When opening more than one file, either:
+ * -# Use document_open_files().
+ * -# Call document_delay_colourise() before document_open_file() and
+ * document_colourise_new() after opening all files.
+ *
+ * This avoids unnecessary recolourising, saving significant processing when a lot of files
+ * are open of a %filetype that supports user typenames, e.g. C.
+ *
+ * @param locale_filename The filename of the %document to load, in locale encoding.
+ * @param readonly Whether to open the %document in read-only mode.
+ * @param ft The %filetype for the %document or @c NULL to auto-detect the %filetype.
+ * @param forced_enc The file encoding to use or @c NULL to auto-detect the file encoding.
+ *
+ * @return The index of the opened file or -1 if an error occurred.
+ **/
gint document_open_file(const gchar *locale_filename, gboolean readonly,
filetype *ft, const gchar *forced_enc)
{
+ /* This is a wrapper for document_open_file_full().
+ * Do not use this when opening multiple files (unless using document_delay_colourise()). */
return document_open_file_full(-1, locale_filename, 0, readonly, ft, forced_enc);
}
@@ -1087,8 +1151,18 @@
}
-/* Takes a linked list of filename URIs and opens each file, ensuring the newly opened
- * documents and existing documents (if necessary) are only colourised once. */
+/**
+ * Opens each file in the list @a filenames, ensuring the newly opened documents and
+ * existing documents (if necessary) are only colourised once.
+ * Internally, document_open_file() is called for every list item.
+ *
+ * @param filenames A list of filenames to load, in locale encoding.
+ * @param readonly Whether to open the %document in read-only mode.
+ * @param ft The %filetype for the %document or @c NULL to auto-detect the %filetype.
+ * @param forced_enc The file encoding to use or @c NULL to auto-detect the file encoding.
+ *
+ * @return The index of the opened file or -1 if an error occurred.
+ **/
void document_open_files(const GSList *filenames, gboolean readonly, filetype *ft,
const gchar *forced_enc)
{
@@ -1104,9 +1178,15 @@
}
-/* Reload document with index idx.
- * forced_enc can be NULL to detect the file encoding.
- * Returns: TRUE if successful. */
+/**
+ * Reloads the %document with the given index @a idx with the specified file encoding
+ * @a forced_enc or @c NULL to auto-detect the file encoding.
+ *
+ * @param idx The %document index for the file to reload.
+ * @param forced_enc The file encoding to use or @c NULL to auto-detect the file encoding.
+ *
+ * @return @a TRUE if the %document was actually reloaded or @a FALSE otherwise.
+ **/
gboolean document_reload_file(gint idx, const gchar *forced_enc)
{
gint pos = 0;
@@ -1170,9 +1250,19 @@
}
-/* This saves the file.
- * When force is set then it is always saved, even if it is unchanged(useful when using Save As)
- * It returns whether the file could be saved or not. */
+/**
+ * Save the %document specified by @a idx. Saving includes replacing tabs by spaces,
+ * stripping trailing spaces and adding a final new line at the end of the file (all only if
+ * user enabled these features). The filetype is set again or auto-detected if it wasn't
+ * set yet. After all, the "document-save" signal is emitted for plugins.
+ *
+ * If the file is not modified, this functions does nothing unless force is set to @c TRUE.
+ *
+ * @param idx The %document index for the file to save.
+ * @param force Whether to save the file even if it is not modified (e.g. for Save As).
+ *
+ * @return @c TRUE if the file was saved or @c FALSE if the file could not or should not be saved.
+ **/
gboolean document_save_file(gint idx, gboolean force)
{
gchar *data;
@@ -2161,6 +2251,14 @@
}
+/**
+ * Sets the encoding of a %document.
+ * This function only set the encoding of the %document, it does not any conversions. The new
+ * encoding is used when e.g. saving the file.
+ *
+ * @param idx The index of the %document.
+ * @param new_encoding The encoding to be set for the %document.
+ **/
void document_set_encoding(gint idx, const gchar *new_encoding)
{
if (! DOC_IDX_VALID(idx) || new_encoding == NULL ||
Modified: trunk/src/document.h
===================================================================
--- trunk/src/document.h 2008-02-16 11:21:24 UTC (rev 2262)
+++ trunk/src/document.h 2008-02-17 18:00:42 UTC (rev 2263)
@@ -21,7 +21,13 @@
* $Id$
*/
+/**
+ * @file document.h
+ * Document related actions: new, save, open, etc.
+ * Also Scintilla search actions.
+ **/
+
#ifndef GEANY_DOCUMENT_H
#define GEANY_DOCUMENT_H 1
@@ -36,72 +42,105 @@
} FileEncoding;
-/* Structure for representing an open tab with all its related stuff. */
+/**
+ * Structure for representing an open tab with all its properties.
+ **/
typedef struct document
{
+ /** General flag to represent this document is active and all properties are set correctly. */
gboolean is_valid;
+ /** Whether this %document support source code symbols(tags) to show in the sidebar. */
gboolean has_tags;
- // the filename is encoded in UTF-8, but every GLibC function expect the locale representation
+ /** The UTF-8 encoded file name. Be careful glibc and GLib functions expect the locale
+ representation of the file name which can be different from this.
+ For conversion into locale encoding for use with file functions of GLib, you can use
+ @ref utils_get_locale_from_utf8. */
gchar *file_name;
+ /** The encoding of the %document, must be a valid string representation of an encoding, can
+ * be retrieved with @ref encodings_get_charset_from_index. */
gchar *encoding;
+ /** Internally used flag to indicate whether the file of this %document has a byte-order-mark. */
gboolean has_bom;
+ /** The filetype for this %document, it's only a reference to one of the elements of the global
+ * filetypes array. */
filetype *file_type;
+ /** TMWorkObject object for this %document. */
TMWorkObject *tm_file;
+ /** The Scintilla object for this %document. */
ScintillaObject *sci;
+ /** GtkLabel shown in the notebook header. */
GtkWidget *tab_label;
+ /** GtkLabel shown in the notebook right-click menu. */
GtkWidget *tabmenu_label;
+ /** GtkTreeView object for this %document within the Open Files treeview of the sidebar. */
GtkWidget *tag_tree;
+ /** GtkTreeStore object for this %document within the Open Files treeview of the sidebar. */
GtkTreeStore *tag_store;
- GtkTreeIter iter; // open files item for this document
+ /** Iter for this %document within the Open Files treeview of the sidebar. */
+ GtkTreeIter iter;
+ /** Whether this %document is read-only. */
gboolean readonly;
+ /** Whether this %document has been changed since it was last saved. */
gboolean changed;
+ /** %Document-specific line wrapping setting. */
gboolean line_wrapping;
+ /** %Document-specific indentation setting. */
gboolean auto_indent;
- gfloat scroll_percent; // % to scroll view by on paint, if positive.
- time_t last_check; // to remember the last disk check
+ /** Percentage to scroll view by on paint, if positive. */
+ gfloat scroll_percent;
+ /** Time of the last disk check. */
+ time_t last_check;
+ /** Modification time of this %document on disk. */
time_t mtime;
+ /** Internally used by the Undo/Redo management code. */
GTrashStack *undo_actions;
+ /** Internally used by the Undo/Redo management code. */
GTrashStack *redo_actions;
+ /** Internally used. */
FileEncoding saved_encoding;
+ /** %Document-specific tab setting. */
gboolean use_tabs;
} document;
-/* dynamic array of document elements to hold all information of the notebook tabs */
+// Dynamic array of document elements to hold all information of the notebook tabs.
extern GArray *doc_array;
-/* doc_list wraps doc_array so it can be used with C array syntax.
- * Example: doc_list[0].sci = NULL; */
+/**
+ * doc_list wraps doc_array so it can be used with C array syntax.
+ * Example: doc_list[0].sci = NULL;
+ **/
#define doc_list ((document *)doc_array->data)
-#define DOC_IDX_VALID(idx) \
- ((idx) >= 0 && (guint)(idx) < doc_array->len && doc_list[idx].is_valid)
+/**
+ * DOC_IDX_VALID checks whether the passed index points to a valid %document object by checking
+ * important properties. It returns FALSE if the index is not valid and then this index
+ * must not be used.
+ **/
+#define DOC_IDX_VALID(doc_idx) \
+ ((doc_idx) >= 0 && (guint)(doc_idx) < doc_array->len && doc_list[doc_idx].is_valid)
+/**
+ * DOC_FILENAME) returns the filename of the %document corresponding to the passed index or
+ * GEANY_STRING_UNTITLED (e.g. _("untitled")) if the %document's filename was not yet set.
+ * This macro never returns NULL.
+ **/
#define DOC_FILENAME(doc_idx) \
- ((doc_list[doc_idx].file_name != NULL) ? \
- (doc_list[doc_idx].file_name) : GEANY_STRING_UNTITLED)
+ ((doc_list[doc_idx].file_name != NULL) ? (doc_list[doc_idx].file_name) : GEANY_STRING_UNTITLED)
-/* returns the document index which has the given filename.
- * is_tm_filename is needed when passing TagManager filenames because they are
- * dereferenced, and would not match the link filename. */
gint document_find_by_filename(const gchar *filename, gboolean is_tm_filename);
-/* returns the document index which has sci */
gint document_find_by_sci(ScintillaObject *sci);
-/* returns the index of the notebook page from the document index */
gint document_get_notebook_page(gint doc_idx);
-/* returns the index of the given notebook page in the document list */
gint document_get_n_idx(guint page_num);
-/* returns the index of the current notebook page in the document list */
gint document_get_cur_idx();
-/* returns NULL if no documents are open */
document *document_get_current();
@@ -113,33 +152,25 @@
void document_set_text_changed(gint idx);
-// Apply just the prefs that can change in the Preferences dialog
void document_apply_update_prefs(gint idx);
-/* removes the given notebook tab and clears the related entry in the document list */
gboolean document_remove(guint page_num);
-/* See document.c. */
gint document_new_file(const gchar *filename, filetype *ft, const gchar *text);
gint document_clone(gint old_idx, const gchar *utf8_filename);
-/* See document.c. */
gint document_open_file(const gchar *locale_filename, gboolean readonly,
filetype *ft, const gchar *forced_enc);
gint document_open_file_full(gint idx, const gchar *filename, gint pos, gboolean readonly,
filetype *ft, const gchar *forced_enc);
-/* Takes a new line separated list of filename URIs and opens each file.
- * length is the length of the string or -1 if it should be detected */
void document_open_file_list(const gchar *data, gssize length);
-/* Takes a linked list of filename URIs and opens each file, ensuring the newly opened
- * documents and existing documents (if necessary) are only colourised once. */
void document_open_files(const GSList *filenames, gboolean readonly, filetype *ft,
const gchar *forced_enc);
@@ -147,16 +178,11 @@
gboolean document_reload_file(gint idx, const gchar *forced_enc);
-/* This saves the file.
- * When force is set then it is always saved, even if it is unchanged(useful when using Save As)
- * It returns whether the file could be saved or not. */
gboolean document_save_file(gint idx, gboolean force);
gboolean document_search_bar_find(gint idx, const gchar *text, gint flags, gboolean inc);
-/* General search function, used from the find dialog.
- * Returns -1 on failure or the start position of the matching text. */
gint document_find_text(gint idx, const gchar *text, gint flags, gboolean search_backwards,
gboolean scroll, GtkWidget *parent);
@@ -173,7 +199,6 @@
void document_update_tag_list(gint idx, gboolean update);
-/* sets the filetype of the document (sets syntax highlighting and tagging) */
void document_set_filetype(gint idx, filetype *type);
gchar *document_get_eol_mode(gint idx);
Modified: trunk/src/encodings.c
===================================================================
--- trunk/src/encodings.c 2008-02-16 11:21:24 UTC (rev 2262)
+++ trunk/src/encodings.c 2008-02-17 18:00:42 UTC (rev 2263)
@@ -178,18 +178,17 @@
}
-/*
- * gtk_status_icon_get_stock:
- * @idx: #GeanyEncodingIndex to retrieve the corresponding character set
+/**
+ * Gets the character set name of the specified index e.g. for use with
+ * @ref document_set_encoding().
*
- * Gets the character set name of the specified index e.g. for use with
- * document_set_encoding.
+ * @param idx @ref GeanyEncodingIndex to retrieve the corresponding character set.
*
- * Return value: charset according to idx,
- * or %NULL if the index is invalid.
*
- * Since: 0.13
- */
+ * @return The charset according to idx, or @c NULL if the index is invalid.
+ *
+ * @since 0.13
+ **/
const gchar* encodings_get_charset_from_index(gint idx)
{
g_return_val_if_fail(idx >= 0 && idx < GEANY_ENCODINGS_MAX, NULL);
@@ -406,19 +405,18 @@
}
-/*
- * encodings_convert_to_utf8_from_charset:
- * @buffer: the input string to convert
- * @size: the length of the string, or -1 if the string is nul-terminated
- * @charset: the charset to be used for conversion
- * @fast: TRUE to only convert the input and skip extended checks on the converted string
+/**
+ * Tries to convert @a buffer into UTF-8 encoding from the encoding specified with @a charset.
+ * If @a fast is not set, additional checks to validate the converted string are performed.
*
- * Tries to convert @buffer into UTF-8 encoding from the encoding specified with @charset.
- * If @fast is not set, additional checks to validate the converted string are performed.
+ * @param buffer The input string to convert.
+ * @param size The length of the string, or -1 if the string is nul-terminated.
+ * @param charset The charset to be used for conversion.
+ * @param fast @c TRUE to only convert the input and skip extended checks on the converted string.
*
- * Return value: If the conversion was successful, a newly allocated nul-terminated string,
- * which must be freed with g_free(). Otherwise %NULL.
- */
+ * @return If the conversion was successful, a newly allocated nul-terminated string,
+ * which must be freed with g_free(). Otherwise @c NULL.
+ **/
gchar *encodings_convert_to_utf8_from_charset(const gchar *buffer, gsize size,
const gchar *charset, gboolean fast)
{
@@ -462,18 +460,17 @@
}
-/*
- * encodings_convert_to_utf8:
- * @buffer: the input string to convert
- * @size: the length of the string, or -1 if the string is nul-terminated.
- * @used_encoding: return location of the detected encoding of the input string, or %NULL
+/**
+ * Tries to convert @a buffer into UTF-8 encoding and store the detected original encoding in
+ * @a used_encoding.
*
- * Tries to convert @buffer into UTF-8 encoding and store the detected original encoding in
- * @used_encoding.
+ * @param buffer the input string to convert.
+ * @param size the length of the string, or -1 if the string is nul-terminated.
+ * @param used_encoding return location of the detected encoding of the input string, or @c NULL.
*
- * Return value: If the conversion was successful, a newly allocated nul-terminated string,
- * which must be freed with g_free(). Otherwise %NULL.
- */
+ * @return If the conversion was successful, a newly allocated nul-terminated string,
+ * which must be freed with g_free(). Otherwise @c NULL.
+ **/
gchar *encodings_convert_to_utf8(const gchar *buffer, gsize size, gchar **used_encoding)
{
gchar *locale_charset = NULL;
Modified: trunk/src/encodings.h
===================================================================
--- trunk/src/encodings.h 2008-02-16 11:21:24 UTC (rev 2262)
+++ trunk/src/encodings.h 2008-02-17 18:00:42 UTC (rev 2263)
@@ -22,6 +22,11 @@
*/
+/**
+ * @file encodings.h
+ * Encoding conversion and Byte Order Mark (BOM) handling.
+ **/
+
/*
* Modified by the gedit Team, 2002. See the gedit AUTHORS file for a
* list of people on the gedit Team.
@@ -47,12 +52,19 @@
GEANY_ENCODING_GROUPS_MAX
} GeanyEncodingGroup;
+
+/** Structure to represent an encoding to be used in Geany. */
typedef struct
{
+ /** The index of the encoding, must be one of GeanyEncodingIndex. */
gint idx;
+ /** Internally used member for grouping */
gint order;
+ /** Internally used member for grouping */
GeanyEncodingGroup group;
+ /** String representation of the encoding, e.g. "ISO-8859-3" */
gchar *charset;
+ /** Translatable and descriptive name of the encoding, e.g. "South European" */
gchar *name;
} GeanyEncoding;
@@ -85,6 +97,10 @@
* Copyright (C) 2002 Red Hat, Inc.
*/
+/**
+ * @enum GeanyEncodingIndex
+ * List of known and supported encodings.
+ **/
typedef enum
{
GEANY_ENCODING_ISO_8859_1,
Modified: trunk/src/plugindata.h
===================================================================
--- trunk/src/plugindata.h 2008-02-16 11:21:24 UTC (rev 2262)
+++ trunk/src/plugindata.h 2008-02-17 18:00:42 UTC (rev 2263)
@@ -25,70 +25,13 @@
#ifndef PLUGIN_H
#define PLUGIN_H
-/**
- * Public symbols supported:
- *
- * version_check()
- * Use VERSION_CHECK() macro instead. Required by Geany.
- *
- * PluginInfo* info()
- * Use PLUGIN_INFO() macro to define it. Required by Geany.
- *
- * GeanyData* geany_data
- * Geany owned fields and functions.
- *
- * PluginFields* plugin_fields
- * Plugin owned fields, including flags.
- *
- * GeanyCallback geany_callbacks[]
- * An array for connecting GeanyObject events, which should be terminated with
- * {NULL, NULL, FALSE, NULL}. See signals below.
- *
- * void configure(GtkWidget *parent)
- * Called when the plugin should show a configure dialog to let the user set some basic
- * plugin configuration. Optionally, can be omitted when not needed.
- *
- * void init(GeanyData *data)
- * Called after loading the plugin. data is the same as geany_data.
- *
- * void cleanup()
- * Called before unloading the plugin. Required for normal plugins - it should undo
- * everything done in init() - e.g. destroy menu items, free memory.
- */
/**
- * Signals:
- *
- * "document-new"
- * Sent when a new document is created.
- * Handler: void user_function(GObject *obj, gint idx, gpointer user_data);
- *
- * "document-open"
- * Sent when a file is opened.
- * Handler: void user_function(GObject *obj, gint idx, gpointer user_data);
- *
- * "document-save"
- * Sent when a file is saved.
- * Handler: void user_function(GObject *obj, gint idx, gpointer user_data);
- *
- * "document-activate"
- * Sent when switching notebook pages.
- * Handler: void user_function(GObject *obj, gint idx, gpointer user_data);
- *
- * "project-open"
- * Sent after a project is opened but before session files are loaded.
- * Handler: void user_function(GObject *obj, GKeyFile *config, gpointer user_data);
- *
- * "project-save"
- * Sent when a project is saved(happens when the project is created, the properties
- * dialog is closed or Geany is exited). This signal is emitted shortly before Geany
- * will write the contents of the GKeyFile to the disc.
- * Handler: void user_function(GObject *obj, GKeyFile *config, gpointer user_data);
- *
- * "project-close"
- * Sent after a project is closed.
- * Handler: void user_function(GObject *obj, gpointer user_data);
- */
+ * @file plugindata.h
+ * This file defines the plugin API, the interface between Geany and its plugins.
+ * For detailed documentation of the plugin system please read the plugin
+ * API documentation.
+ **/
/* The API version should be incremented whenever any plugin data types below are
@@ -142,17 +85,23 @@
}
-/* For geany_callbacks array - see top of file. */
+/** callback array entry */
typedef struct GeanyCallback
{
+ /** The name of signal, must be an existing signal. For a list of available signals,
+ * please see the @link signals Signal documentation @endlink. */
gchar *signal_name;
+ /** A callback function which is called when the signal is emitted. */
GCallback callback;
+ /** Set to TRUE to connect your handler with g_signal_connect_after(). */
gboolean after;
+ /** The user data passed to the signal handler. */
gpointer user_data;
}
GeanyCallback;
+
typedef enum
{
PLUGIN_IS_DOCUMENT_SENSITIVE = 1 << 0 // if menu_item should be disabled when there are no documents
Modified: trunk/src/utils.c
===================================================================
--- trunk/src/utils.c 2008-02-16 11:21:24 UTC (rev 2262)
+++ trunk/src/utils.c 2008-02-17 18:00:42 UTC (rev 2263)
@@ -223,6 +223,17 @@
}
+/**
+ * Write the given @c text into a file with @c filename.
+ * If the file doesn't exist, it will be created.
+ * If it already exists, it will be overwritten.
+ *
+ * @param filename The filename of the file to write, in locale encoding.
+ * @param text The text to write into the file.
+ *
+ * @return 0 if the directory was successfully created, otherwise the @c errno of the
+ * failed operation is returned.
+ **/
gint utils_write_file(const gchar *filename, const gchar *text)
{
FILE *fp;
@@ -639,12 +650,18 @@
}
-/* (taken from libexo from os-cillation)
- * NULL-safe string comparison. Returns TRUE if both a and b are
- * NULL or if a and b refer to valid strings which are equal.
- */
+/**
+ * @a NULL-safe string comparison. Returns @a TRUE if both @c a and @c b are @a NULL
+ * or if @c a and @c b refer to valid strings which are equal.
+ *
+ * @param a Pointer to first string or @a NULL.
+ * @param b Pointer to first string or @a NULL.
+ *
+ * @return @a TRUE if @c a equals @c b, else @a FALSE.
+ **/
gboolean utils_str_equal(const gchar *a, const gchar *b)
{
+ /* (taken from libexo from os-cillation) */
if (a == NULL && b == NULL) return TRUE;
else if (a == NULL || b == NULL) return FALSE;
@@ -656,8 +673,13 @@
}
-/* removes the extension from filename and return the result in
- * a newly allocated string */
+/**
+ * Remove the extension from @c filename and return the result in a newly allocated string.
+ *
+ * @param filename The filename to operate on.
+ *
+ * @return A newly-allocated string, should be freed when no longer needed.
+ **/
gchar *utils_remove_ext_from_filename(const gchar *filename)
{
gchar *last_dot = strrchr(filename, '.');
@@ -938,8 +960,20 @@
}
-/* Wrapper functions for Key-File-Parser from GLib in keyfile.c to reduce code size */
-gint utils_get_setting_integer(GKeyFile *config, const gchar *section, const gchar *key, const gint default_value)
+/**
+ * Convenience function for g_key_file_get_integer() to add a default value argument.
+ *
+ * @param config A GKeyFile object.
+ * @param section The group name to look in for the key.
+ * @param key The key to find.
+ * @param default_value The default value which will be returned when @c section or @c key
+ * don't exist.
+ *
+ * @return The value associated with c key as an integer, or the given default value if the value
+ * could not be retrieved.
+ **/
+gint utils_get_setting_integer(GKeyFile *config, const gchar *section, const gchar *key,
+ const gint default_value)
{
gint tmp;
GError *error = NULL;
@@ -956,7 +990,20 @@
}
-gboolean utils_get_setting_boolean(GKeyFile *config, const gchar *section, const gchar *key, const gboolean default_value)
+/**
+ * Convenience function for g_key_file_get_boolean() to add a default value argument.
+ *
+ * @param config A GKeyFile object.
+ * @param section The group name to look in for the key.
+ * @param key The key to find.
+ * @param default_value The default value which will be returned when @c section or @c key
+ * don't exist.
+ *
+ * @return The value associated with c key as a boolean, or the given default value if the value
+ * could not be retrieved.
+ **/
+gboolean utils_get_setting_boolean(GKeyFile *config, const gchar *section, const gchar *key,
+ const gboolean default_value)
{
gboolean tmp;
GError *error = NULL;
@@ -973,7 +1020,20 @@
}
-gchar *utils_get_setting_string(GKeyFile *config, const gchar *section, const gchar *key, const gchar *default_value)
+/**
+ * Convenience function for g_key_file_get_string() to add a default value argument.
+ *
+ * @param config A GKeyFile object.
+ * @param section The group name to look in for the key.
+ * @param key The key to find.
+ * @param default_value The default value which will be returned when @c section or @c key
+ * don't exist.
+ *
+ * @return A newly allocated string, or the given default value if the value could not be
+ * retrieved.
+ **/
+gchar *utils_get_setting_string(GKeyFile *config, const gchar *section, const gchar *key,
+ const gchar *default_value)
{
gchar *tmp;
GError *error = NULL;
@@ -1086,8 +1146,8 @@
/* taken from busybox, thanks */
-gchar *utils_make_human_readable_str(unsigned long long size, unsigned long block_size,
- unsigned long display_unit)
+gchar *utils_make_human_readable_str(unsigned long long size, gulong block_size,
+ gulong display_unit)
{
/* The code will adjust for additional (appended) units. */
static const gchar zero_and_units[] = { '0', 0, 'K', 'M', 'G', 'T' };
@@ -1179,7 +1239,7 @@
}
-// Returns: new string with the current time formatted HH:MM:SS.
+// Returns: newly allocated string with the current time formatted HH:MM:SS.
gchar *utils_get_current_time_string()
{
const time_t tp = time(NULL);
@@ -1402,7 +1462,15 @@
}
-/* Null-safe with fallback encoding conversion. */
+/**
+ * Converts the given UTF-8 encoded string into locale encoding.
+ * On Windows platforms, it does nothing and instead it just returns a copy of the input string.
+ *
+ * @param utf8_text UTF-8 encoded text.
+ *
+ * @return The converted string in locale encoding, or a copy of the input string if conversion
+ * failed. Should be freed with g_free(). If @a utf8_text is @c NULL, @c NULL is returned.
+ **/
gchar *utils_get_locale_from_utf8(const gchar *utf8_text)
{
#ifdef G_OS_WIN32
@@ -1422,7 +1490,15 @@
}
-/* Null-safe with fallback encoding conversion. */
+/**
+ * Converts the given string (in locale encoding) into UTF-8 encoding.
+ * On Windows platforms, it does nothing and instead it just returns a copy of the input string.
+ *
+ * @param locale_text Text in locale encoding.
+ *
+ * @return The converted string in UTF-8 encoding, or a copy of the input string if conversion
+ * failed. Should be freed with g_free(). If @a locale_text is @c NULL, @c NULL is returned.
+ **/
gchar *utils_get_utf8_from_locale(const gchar *locale_text)
{
#ifdef G_OS_WIN32
@@ -1575,6 +1651,16 @@
#endif
+/**
+ * Create a directory if it doesn't already exist.
+ * Create intermediate parent directories as needed, too.
+ *
+ * @param path The path of the directory to create, in locale encoding.
+ * @param create_parent_dirs Whether to create intermediate parent directories if necessary.
+ *
+ * @return 0 if the directory was successfully created, otherwise the @c errno of the
+ * failed operation is returned.
+ **/
gint utils_mkdir(const gchar *path, gboolean create_parent_dirs)
{
gint mode = 0700;
@@ -1590,12 +1676,19 @@
}
-/* Gets a sorted list of files from the specified directory.
- * Locale encoding is expected for path and used for the file list.
- * The list and the data in the list should be freed after use.
- * Returns: The list or NULL if no files found.
- * length will point to the number of non-NULL data items in the list, unless NULL.
- * error is the location for storing a possible error, or NULL. */
+/**
+ * Gets a sorted list of files from the specified directory.
+ * Locale encoding is expected for path and used for the file list. The list and the data
+ * in the list should be freed after use.
+ *
+ * @param path The path of the directory to scan, in locale encoding.
+ * @param length The location to store the number of non- at a NULL data items in the list,
+ * unless @a NULL.
+ * @param error The is the location for storing a possible error, or @a NULL.
+ *
+ * @return A newly allocated list or @a NULL if no files found. The list and its data should be
+ * freed when no longer needed.
+ **/
GSList *utils_get_file_list(const gchar *path, guint *length, GError **error)
{
GSList *list = NULL;
@@ -1648,10 +1741,18 @@
}
-/* Replaces all occurrences of needle in str with replace.
- * Currently this is not safe if replace matches needle.
- * Returns: TRUE if needle was found. */
-gboolean utils_string_replace_all(GString *str, const gchar *needle, const gchar *replace)
+/**
+ * Replaces all occurrences of @c needle in @c haystack with @c replace.
+ * Currently this is not safe if @c replace matches @c needle, so @c needle and @c replace
+ * must not be equal.
+ *
+ * @param haystack The input string to operate on. This string is modified in place.
+ * @param needle The string which should be replaced.
+ * @param replace The replacement for @c needle.
+ *
+ * @return @a TRUE if @c needle was found, else @a FALSE.
+ **/
+gboolean utils_string_replace_all(GString *haystack, const gchar *needle, const gchar *replace)
{
const gchar *c;
gssize pos = -1;
@@ -1661,15 +1762,15 @@
while (1)
{
- c = strstr(str->str, needle);
+ c = strstr(haystack->str, needle);
if (c == NULL)
break;
else
{
- pos = c - str->str;
- g_string_erase(str, pos, strlen(needle));
+ pos = c - haystack->str;
+ g_string_erase(haystack, pos, strlen(needle));
if (replace)
- g_string_insert(str, pos, replace);
+ g_string_insert(haystack, pos, replace);
}
}
return (pos != -1);
Modified: trunk/src/utils.h
===================================================================
--- trunk/src/utils.h 2008-02-16 11:21:24 UTC (rev 2262)
+++ trunk/src/utils.h 2008-02-17 18:00:42 UTC (rev 2263)
@@ -21,18 +21,24 @@
* $Id$
*/
+/**
+ * @file: utils.h
+ * General utility functions, non-GTK related.
+ */
#ifndef GEANY_UTILS_H
#define GEANY_UTILS_H 1
-// Returns: TRUE if ptr points to a non-zero value.
+/** Returns: TRUE if @a ptr points to a non-zero value. */
#define NZV(ptr) \
((ptr) && (ptr)[0])
-/* Free's ptr (if not NULL), then assigns result to it.
- * result can be an expression using the 'old' value of ptr.
- * It prevents a memory leak compared with: ptr = func(ptr); */
-#define setptr(ptr, result)\
+/**
+ * Free's @a ptr (if not @c NULL), then assigns @a result to it.
+ * @a result can be an expression using the 'old' value of @a ptr.
+ * It prevents a memory leak compared with: @code ptr = func(ptr); @endcode
+ **/
+#define setptr(ptr, result) \
{\
gpointer setptr_tmp = ptr;\
ptr = result;\
@@ -42,7 +48,6 @@
void utils_start_browser(const gchar *uri);
-/* taken from anjuta, to determine the EOL mode of the file */
gint utils_get_line_endings(gchar* buffer, glong size);
gboolean utils_isbrace(gchar c, gboolean include_angles);
@@ -59,13 +64,10 @@
gboolean utils_check_disk_status(gint idx, gboolean force);
-//gchar *utils_get_current_tag(gint idx, gint direction);
gint utils_get_current_function(gint idx, const gchar **tagname);
-/* returns the end-of-line character(s) length of the specified editor */
gint utils_get_eol_char_len(gint idx);
-/* returns the end-of-line character(s) of the specified editor */
const gchar *utils_get_eol_char(gint idx);
gboolean utils_atob(const gchar *str);
@@ -74,31 +76,22 @@
gdouble utils_scale_round(gdouble val, gdouble factor);
-/* (taken from libexo from os-cillation)
- * NULL-safe string comparison. Returns TRUE if both a and b are
- * NULL or if a and b refer to valid strings which are equal.
- */
gboolean utils_str_equal(const gchar *a, const gchar *b);
-/* removes the extension from filename and return the result in
- * a newly allocated string */
gchar *utils_remove_ext_from_filename(const gchar *filename);
-
gchar utils_brace_opposite(gchar ch);
gchar *utils_get_hostname();
gint utils_make_settings_dir();
-
gboolean utils_string_replace_all(GString *str, const gchar *needle, const gchar *replace);
gchar *utils_str_replace(gchar *haystack, const gchar *needle, const gchar *replacement);
gint utils_strpos(const gchar* haystack, const gchar * needle);
-
gchar *utils_get_date_time(const gchar *format, time_t *time_to_use);
gchar *utils_get_initials(gchar *name);
@@ -121,15 +114,11 @@
void utils_beep();
-gchar *utils_make_human_readable_str(unsigned long long size, unsigned long block_size,
- unsigned long display_unit);
+gchar *utils_make_human_readable_str(unsigned long long size, gulong block_size,
+ gulong display_unit);
-/* utils_strtod() converts a string containing a hex colour ("0x00ff00") into an integer.
- * Basically, it is the same as strtod() would do, but it does not understand hex colour values,
- * before ANSI-C99. With with_route set, it takes strings of the format "#00ff00". */
gint utils_strtod(const gchar *source, gchar **end, gboolean with_route);
-// returned string must be freed.
gchar *utils_get_current_time_string();
GIOChannel *utils_set_up_io_channel(gint fd, GIOCondition cond, gboolean nblock,
@@ -137,37 +126,20 @@
gchar **utils_read_file_in_array(const gchar *filename);
-/* Contributed by Stefan Oltmanns, thanks.
- * Replaces \\, \r, \n, \t and \uXXX by their real counterparts */
gboolean utils_str_replace_escape(gchar *string);
-/* Wraps a string in place, replacing a space with a newline character.
- * wrapstart is the minimum position to start wrapping or -1 for default */
gboolean utils_wrap_string(gchar *string, gint wrapstart);
-/* Simple wrapper for g_locale_from_utf8; returns a copy of utf8_text on failure. */
gchar *utils_get_locale_from_utf8(const gchar *utf8_text);
-/* Simple wrapper for g_locale_to_utf8; returns a copy of locale_text on failure. */
gchar *utils_get_utf8_from_locale(const gchar *locale_text);
-
-/* Frees all passed pointers if they are *ALL* non-NULL.
- * Do not use if any pointers may be NULL.
- * The first argument is nothing special, it will also be freed.
- * The list must be ended with NULL. */
void utils_free_pointers(gpointer first, ...) G_GNUC_NULL_TERMINATED;
-/* Creates a string array deep copy of a series of non-NULL strings.
- * The first argument is nothing special.
- * The list must be ended with NULL.
- * If first is NULL, NULL is returned. */
gchar **utils_strv_new(gchar *first, ...) G_GNUC_NULL_TERMINATED;
-
gint utils_mkdir(const gchar *path, gboolean create_parent_dirs);
-/* Gets a sorted list of files in the specified directory. */
GSList *utils_get_file_list(const gchar *path, guint *length, GError **error);
gboolean utils_str_has_upper(const gchar *str);
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
More information about the Commits
mailing list