From 529c49df5aba41b66100e5bba04c82ebcf59f70a Mon Sep 17 00:00:00 2001 From: quaker Date: Sun, 11 Jan 2009 10:27:01 +0000 Subject: [PATCH] Added some missing files for make doc support git-svn-id: svn+ssh://svn.enlightenment.org/var/svn/e/trunk/ecore@38546 7cbeb6ba-43b4-40fd-8cce-4c39aea84d33 --- doc/Doxyfile | 138 ++++++++++++++++++++ doc/ecore.dox.in | 378 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ m4/efl_doxygen.m4 | 88 +++++++++++++ 3 files changed, 604 insertions(+) create mode 100644 doc/Doxyfile create mode 100644 doc/ecore.dox.in create mode 100644 m4/efl_doxygen.m4 diff --git a/doc/Doxyfile b/doc/Doxyfile new file mode 100644 index 0000000..f898c07 --- /dev/null +++ b/doc/Doxyfile @@ -0,0 +1,138 @@ +PROJECT_NAME = Ecore +PROJECT_NUMBER = +OUTPUT_DIRECTORY = . +INPUT = ./ecore.dox ../src/lib +IMAGE_PATH = img +OUTPUT_LANGUAGE = English +GENERATE_HTML = YES +HTML_OUTPUT = html +HTML_FILE_EXTENSION = .html +HTML_HEADER = head.html +HTML_FOOTER = foot.html +HTML_STYLESHEET = e.css +HTML_ALIGN_MEMBERS = YES +ENUM_VALUES_PER_LINE = 1 +GENERATE_HTMLHELP = NO +CHM_FILE = +HHC_LOCATION = +GENERATE_CHI = NO +BINARY_TOC = NO +TOC_EXPAND = NO +DISABLE_INDEX = YES +EXTRACT_ALL = NO +EXTRACT_PRIVATE = NO +EXTRACT_STATIC = NO +EXTRACT_LOCAL_CLASSES = NO +HIDE_UNDOC_MEMBERS = YES +HIDE_UNDOC_CLASSES = YES +HIDE_FRIEND_COMPOUNDS = YES +BRIEF_MEMBER_DESC = YES +REPEAT_BRIEF = YES +ALWAYS_DETAILED_SEC = NO +INLINE_INHERITED_MEMB = NO +FULL_PATH_NAMES = NO +STRIP_FROM_PATH = +INTERNAL_DOCS = NO +STRIP_CODE_COMMENTS = YES +CASE_SENSE_NAMES = YES +SHORT_NAMES = NO +HIDE_SCOPE_NAMES = NO +VERBATIM_HEADERS = NO +SHOW_INCLUDE_FILES = NO +JAVADOC_AUTOBRIEF = YES +MULTILINE_CPP_IS_BRIEF = NO +DETAILS_AT_TOP = NO +INHERIT_DOCS = YES +INLINE_INFO = YES +SORT_MEMBER_DOCS = YES +DISTRIBUTE_GROUP_DOC = NO +TAB_SIZE = 2 +GENERATE_TODOLIST = YES +GENERATE_TESTLIST = YES +GENERATE_BUGLIST = YES +GENERATE_DEPRECATEDLIST= YES +ALIASES = +ENABLED_SECTIONS = +MAX_INITIALIZER_LINES = 30 +OPTIMIZE_OUTPUT_FOR_C = YES +OPTIMIZE_OUTPUT_JAVA = NO +SHOW_USED_FILES = NO +QUIET = YES +WARNINGS = YES +WARN_IF_UNDOCUMENTED = YES +WARN_FORMAT = "$file:$line: $text" +WARN_LOGFILE = +FILE_PATTERNS = +RECURSIVE = YES +EXCLUDE_SYMLINKS = NO +EXCLUDE_PATTERNS = +EXAMPLE_PATH = ../examples/ +EXAMPLE_PATTERNS = +EXAMPLE_RECURSIVE = NO +INPUT_FILTER = +FILTER_SOURCE_FILES = NO +SOURCE_BROWSER = NO +INLINE_SOURCES = NO +REFERENCED_BY_RELATION = YES +REFERENCES_RELATION = YES +ALPHABETICAL_INDEX = YES +COLS_IN_ALPHA_INDEX = 2 +IGNORE_PREFIX = +GENERATE_TREEVIEW = NO +TREEVIEW_WIDTH = 250 +GENERATE_LATEX = YES +LATEX_OUTPUT = latex +LATEX_CMD_NAME = latex +MAKEINDEX_CMD_NAME = makeindex +COMPACT_LATEX = NO +PAPER_TYPE = a4wide +EXTRA_PACKAGES = +LATEX_HEADER = +PDF_HYPERLINKS = YES +USE_PDFLATEX = NO +LATEX_BATCHMODE = NO +GENERATE_RTF = NO +RTF_OUTPUT = rtf +COMPACT_RTF = NO +RTF_HYPERLINKS = NO +RTF_STYLESHEET_FILE = +RTF_EXTENSIONS_FILE = +GENERATE_MAN = YES +MAN_OUTPUT = man +MAN_EXTENSION = .3 +MAN_LINKS = YES +GENERATE_XML = NO +XML_SCHEMA = +XML_DTD = +GENERATE_AUTOGEN_DEF = NO +ENABLE_PREPROCESSING = YES +MACRO_EXPANSION = NO +EXPAND_ONLY_PREDEF = NO +SEARCH_INCLUDES = NO +INCLUDE_PATH = +INCLUDE_FILE_PATTERNS = +PREDEFINED = +EXPAND_AS_DEFINED = +SKIP_FUNCTION_MACROS = YES +TAGFILES = +GENERATE_TAGFILE = +ALLEXTERNALS = NO +EXTERNAL_GROUPS = YES +PERL_PATH = /usr/bin/perl +CLASS_DIAGRAMS = NO +HIDE_UNDOC_RELATIONS = YES +HAVE_DOT = NO +CLASS_GRAPH = NO +COLLABORATION_GRAPH = NO +TEMPLATE_RELATIONS = NO +INCLUDE_GRAPH = NO +INCLUDED_BY_GRAPH = NO +GRAPHICAL_HIERARCHY = NO +DOT_IMAGE_FORMAT = png +DOT_PATH = +DOTFILE_DIRS = +MAX_DOT_GRAPH_WIDTH = 512 +MAX_DOT_GRAPH_HEIGHT = 512 +GENERATE_LEGEND = YES +DOT_CLEANUP = YES +SEARCHENGINE = NO diff --git a/doc/ecore.dox.in b/doc/ecore.dox.in new file mode 100644 index 0000000..07cf5bf --- /dev/null +++ b/doc/ecore.dox.in @@ -0,0 +1,378 @@ +/** +@brief Ecore Library Public API Calls + +These routines are used for Ecore Library interaction +*/ + +/** + +@mainpage Ecore + +@image latex ecore_big.eps width=5cm +@image html ecore.png + +@version @PACKAGE_VERSION@ +@author Carsten Haitzler +@author Tom Gilbert +@author Burra +@author Chris Ross +@author Term +@author Tilman Sauerbeck +@author Nathan Ingersoll +@date 2000-2004 + +@section intro Introduction + +Ecore is a library of convenience functions. + +The Ecore library provides the following modules: +@li @link Ecore.h Ecore - Main Loop Functions. @endlink +@li @link Ecore_Con.h Ecore_Con - Connection functions. @endlink +@li @link Ecore_Config.h Ecore_Config - Configuration functions. @endlink +@li @link Ecore_Evas.h Ecore_Evas - Evas convenience functions. @endlink +@li @link Ecore_Fb.h Ecore_FB - Frame buffer convenience functions. @endlink +@li @link Ecore_Ipc.h Ecore_IPC - Inter Process Communication functions. @endlink +@li @link Ecore_Job.h Ecore_Job - Job functions, to be used in the Ecore main loop. @endlink +@li @link Ecore_Txt.h Ecore_Txt - Text encoding conversion. @endlink +@li @link Ecore_X.h Ecore_X - X Windows System wrapper. @endlink + +@section compiling How to compile using Ecore? + +This section has to be documented. Below is just a quick line to handle all +Ecore modules at once. + +@verbatim +gcc *.c \ +-I/usr/local/include -I/usr/X11R6/include \ +-L/usr/local/lib -L/usr/X11R6/lib \ +-lecore -lecore_evas -lecore_x -lecore_fb -lecore_job \ +`pkg-config evas --cflags --libs` +@endverbatim + +@section install How is it installed? + +Suggested configure options for evas for a Linux desktop X display: + +@verbatim +./configure \ +--enable-ecore-x \ +--enable-ecore-fb \ +--enable-ecore-evas \ +--enable-ecore-evas-gl \ +--enable-ecore-job \ +--enable-ecore-con \ +--enable-ecore-ipc \ +--enable-ecore-txt +make CFLAGS="-O9 -mpentiumpro -march=pentiumpro -mcpu=pentiumpro" +@endverbatim + +@todo (1.0) Document API + +*/ + +/* +@page Ecore_Main_Loop_Page The Ecore Main Loop + +@section intro What is Ecore? + +Ecore is a clean and tiny event loop library with many modules to do lots of +convenient things for a programmer, to save time and effort. + +It's small and lean, designed to work on embedded systems all the way to +large and powerful multi-cpu workstations. It serialises all system signals, +events etc. into a single event queue, that is easily processed without +needing to worry about concurrency. A properly written, event-driven program +using this kind of programming doesn't need threads, nor has to worry about +concurrency. It turns a program into a state machine, and makes it very +robust and easy to follow. + +Ecore gives you other handy primitives, such as timers to tick over for you +and call specified functions at particular times so the programmer can use +this to do things, like animate, or time out on connections or tasks that take +too long etc. + +Idle handlers are provided too, as well as calls on entering an idle state +(often a very good time to update the state of the program). All events that +enter the system are passed to specific callback functions that the program +sets up to handle those events. Handling them is simple and other Ecore +modules produce more events on the queue, coming from other sources such as +file descriptors etc. + +Ecore also lets you have functions called when file descriptors become active +for reading or writing, allowing for streamlined, non-blocking IO. + +Here is an exmaple of a simple program and its basic event loop flow: + +@image html prog_flow.png + + + +@section work How does Ecore work? + +Ecore is very easy to learn and use. All the function calls are designed to +be easy to remember, explicit in describing what they do, and heavily +name-spaced. Ecore programs can start and be very simple. + +For example: + +@code +#include + +int main(int argc, const char **argv) +{ + ecore_init(); + ecore_app_args_set(argc, argv); + ecore_main_loop_begin(); + ecore_shutdown(); + return 0; +} +@endcode + +This program is very simple and does't check for errors, but it does start up +and begin a main loop waiting for events or timers to tick off. This program +doesn't set up any, but now we can expand on this simple program a little +more by adding some event handlers and timers. + +@code +#include + +Ecore_Timer *timer1 = NULL; +Ecore_Event_Handler *handler1 = NULL; +double start_time = 0.0; + +int timer_func(void *data) +{ + printf("Tick timer. Sec: %3.2f\n", ecore_time_get() - start_time); + return 1; +} + +int exit_func(void *data, int ev_type, void *ev) +{ + Ecore_Event_Signal_Exit *e; + + e = (Ecore_Event_Signal_Exit *)ev; + if (e->interrupt) printf("Exit: interrupt\n"); + else if (e->quit) printf("Exit: quit\n"); + else if (e->terminate) printf("Exit: terminate\n"); + ecore_main_loop_quit(); + return 1; +} + +int main(int argc, const char **argv) +{ + ecore_init(); + ecore_app_args_set(argc, argv); + start_time = ecore_time_get(); + handler1 = ecore_event_handler_add(ECORE_EVENT_SIGNAL_EXIT, exit_func, NULL); + timer1 = ecore_timer_add(0.5, timer_func, NULL); + ecore_main_loop_begin(); + ecore_shutdown(); + return 0; +} +@endcode + +In the previous example, we initialize our application and get the time at +which our program has started so we can calculate an offset. We set +up a timer to tick off in 0.5 seconds, and since it returns 1, will +keep ticking off every 0.5 seconds until it returns 0, or is deleted +by hand. An event handler is set up to call a function - exit_func(), +whenever an event of type ECORE_EVENT_SIGNAL_EXIT is received (CTRL-C +on the command line will cause such an event to happen). If this event +occurs it tells you what kind of exit signal was received, and asks +the main loop to quit when it is finished by calling +ecore_main_loop_quit(). + +The handles returned by ecore_timer_add() and ecore_event_handler_add() are +only stored here as an example. If you don't need to address the timer or +event handler again you don't need to store the result, so just call the +function, and don't assign the result to any variable. + +This program looks slightly more complex than needed to do these simple +things, but in principle, programs don't get any more complex. You add more +event handlers, for more events, will have more timers and such, BUT it all +follows the same principles as shown in this example. + +*/ + +/** +@page Ecore_Config_Page The Enlightened Property Library + +The Enlightened Property Library (Ecore_Config) is an adbstraction +from the complexities of writing your own configuration. It provides +many features using the Enlightenment 17 development libraries. + +To use the library, you: +@li Set the default values of your properties. +@li Load the configuration from a file. You must set the default values + first, so that the library knows the correct type of each argument. + +The following examples show how to use the Enlightened Property Library: +@li @link config_basic_example.c config_basic_example.c @endlink +@li @link config_listener_example.c config_listener_example.c @endlink + +*/ + +/** +@page Ecore_ADT_Page Ecore Abstract Data Types + +This page briefly describes the different abstract data types +that are provided by the Ecore library for general usage. You need to +include the @link Ecore_Data.h Ecore_Data.h @endlink to use them. + +@section Ecore_ADT_List List + +A list is a simple data type where one each piece of data points to +another piece of data. + +Associated modules that describe the List ADT include: +@li @ref Ecore_Data_List_Creation_Group +@li @ref Ecore_Data_List_Add_Item_Group +@li @ref Ecore_Data_List_Remove_Item_Group +@li @ref Ecore_Data_List_Traverse_Group +@li @ref Ecore_Data_List_Node_Group + +Examples involving lists include: +@li @link list_example.c list_example.c @endlink + +@section Ecore_ADT_DList Doubly Linked List + +A doubly linked list is like a linked list, only each piece of data +can also point to the piece before it. In other words, you can traverse +a doubly linked list in both directions. + +Associated modules that describe the DList ADT include: +@li @ref Ecore_Data_DList_Creation_Group +@li @ref Ecore_Data_DList_Add_Item_Group +@li @ref Ecore_Data_DList_Remove_Item_Group + +@section Ecore_ADT_Hash Hash + +A hash is an abstract data type where one value is associated with another +value. Instead of each element of the group being accessible using a +number, each element is accessed using another object. + +Associated modules that describe the Hash ADT include: +@li @ref Ecore_Data_Hash_ADT_Creation_Group +@li @ref Ecore_Data_Hash_ADT_Destruction_Group +@li @ref Ecore_Data_Hash_ADT_Data_Group + +@todo Finish this. +*/ + +/** +@page X_Window_System_Page X Window System + +The Ecore library includes a wrapper for handling the X window system. +This page briefly explains what the X window system is and various terms +that are used. +*/ + +// GROUP DEFINITIONS + +/** +@defgroup Ecore_Timer_Group Ecore Timer + +The timer allows callbacks to be called at specific intervals. + */ + +/** +@defgroup Ecore_Job_Group Ecore Jobs + +You can queue jobs that are to be done by the main loop when the current +event is dealt with. +*/ + +/** +@defgroup Idle_Group Idle Handlers + +Callbacks that are called when the program enters or exits an idle state. + +The ecore main loop enters an idle state when it is waiting for timers +to time out, data to come in on a file descriptor or any other event +to occur. You can set callbacks to be called when the main loop +enters an idle state, during an idle state or just after the program +wakes up. + +Enterer callbacks are good for updating your program's state, if it +has a state engine. Once all of the enterer handlers are called, the +program will enter a "sleeping" state. + +Idler callbacks are called when the main loop has called all enterer +handlers. They are useful for interfaces that require polling and +timers would be too slow to use. + +If no idler callbacks are specified, then the process literally goes +to sleep. Otherwise, the idler callbacks are called continuously +while the loop is "idle", using as much CPU as is available to the +process. + +Exiter callbacks are called when the main loop wakes up from an idle +state. + +*/ + +/** +@defgroup Ecore_Config_Create_Group Ecore Config Create Functions + +Convenience functions that set default values, bounds, option values and +descriptions in one call. +*/ + +/** +@defgroup Ecore_Config_File_Group Ecore Config File Functions + +Functions that are used to load and save properties from and to files. +*/ + +// EXAMPLES + +/** +@example args_example.c +Shows how to set and retrieve the program arguments. +*/ + +/** +@example con_server_example.c +Shows how to write a simple server using the Ecore_Con library. +*/ + +/** +@example con_client_example.c +Shows how to write a simple client, that connects to the example server. +*/ + +/** +@example event_handler_example.c +Shows how to use event handlers. +*/ + +/** +@example timer_example.c +Demonstrates use of the ecore_timer. +*/ + +/** +@example config_basic_example.c +Provides an example of how to use the basic configuration functions. +See the file Ecore_Config.h for the full list of available functions. +*/ + +/** +@example config_listener_example.c +Shows how to set up a listener to listen for configuration changes. +*/ + +/** +@example list_example.c +Provides a basic example of how to append to and traverse a list. +*/ + +/** +@example list_destroy_example.c +Shows how to set and use a destructor for an Ecore_List. +*/ + +/** +@example x_window_example.c +Shows the basics of using the X Windows system through Ecore functions. +*/ diff --git a/m4/efl_doxygen.m4 b/m4/efl_doxygen.m4 new file mode 100644 index 0000000..49a3dfa --- /dev/null +++ b/m4/efl_doxygen.m4 @@ -0,0 +1,88 @@ +dnl Copyright (C) 2008 Vincent Torri +dnl That code is public domain and can be freely used or copied. + +dnl Macro that check if doxygen is available or not. + +dnl EFL_CHECK_DOXYGEN([ACTION-IF-FOUND [, ACTION-IF-NOT-FOUND]]) +dnl Test for the doxygen program +dnl Defines DOXYGEN +dnl Defines the automake conditionnal EFL_BUILD_DOC +dnl +AC_DEFUN([EFL_CHECK_DOXYGEN], +[ + +DOXYGEN="doxygen" + +dnl +dnl Disable the build of the documentation +dnl +AC_ARG_ENABLE([doc], + AC_HELP_STRING( + [--disable-doc], + [Disable the build of the documentation]), + [if test "${disable_doc}" = "yes" ; then + enable_doc="no" + else + enable_doc="yes" + fi], + [enable_doc="yes"] +) + +dnl +dnl Specify the full file name, with path +dnl +AC_ARG_WITH([doxygen], + AC_HELP_STRING( + [--with-doxygen=FILE], + [doxygen program to use @<:@default=doxygen@:>@]), + dnl + dnl Check the given doxygen program. + dnl + [DOXYGEN=${withval} + AC_CHECK_PROG([BUILD_DOCS], + [${DOXYGEN}], + [yes], + [no]) + if test "x${BUILD_DOCS}" = "xno" ; then + echo "WARNING:" + echo "The doxygen program you specified:" + echo "$DOXYGEN" + echo "was not found. Please check the path and make sure " + echo "the program exists and is executable." + AC_MSG_WARN([Warning: no doxygen detected. Documentation will not be built]) + fi + ], + [AC_CHECK_PROG([BUILD_DOCS], + [${DOXYGEN}], + [yes], + [no]) + if test "x${BUILD_DOCS}" = "xno" ; then + echo "WARNING:" + echo "The doxygen program was not found in your execute" + echo "You may have doxygen installed somewhere not covered by your path." + echo "" + echo "If this is the case make sure you have the packages installed, AND" + echo "that the doxygen program is in your execute path (see your" + echo "shell manual page on setting the \$PATH environment variable), OR" + echo "alternatively, specify the program to use with --with-doxygen." + AC_MSG_WARN([Warning: no doxygen detected. Documentation will not be built]) + fi + ] +) + +dnl +dnl Substitution +dnl +AC_SUBST([DOXYGEN]) + +AM_CONDITIONAL(EFL_BUILD_DOC, test "x${BUILD_DOCS}" = "xyes") + +if test "x${BUILD_DOCS}" = "xyes" ; then + ifelse([$1], , :, [$1]) +else + ifelse([$2], , :, [$2]) +fi + +]) + +dnl End of doxygen.m4 -- 2.7.4