SF.net SVN: geany: [2263] trunk

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-@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.