I noticed that some help with documentation is needed, so I started
poking around the documentation generation code in Ecore. I have been
able to make doxygen generate a proper file list for the Ecore
documentation. Instead of attributing all functions to the file
ecore.c, functions can now be attributed to the header file in which
they are prototyped.
A copy of the newly generated documentation can be downloaded from
http://home.bigblue.net.au/quasar/ecore_docs.tar.gz. The patch to do
this from the source is attached, if you are interested in using it in
Ecore.
What the patch does:
- Stops gendoc from creating ecore.c.
- Tells doxygen (through the Doxyfile) to use ecore.c.in and the source
files in the src/lib directory (searching recursively) to generate
the documentation.
- Removes the @file statement from ecore.c.in, to prevent it appearing
in the file list.
- Adds @file and @brief statements to the public header files.
You still need to run 'make' before you can generate the docs with
gendoc, as some of the header files (with their embedded doxygen
statements) are created at compile time.
If I were to write documentation for Ecore, who can I ask stupid
questions about the code, and to whom could I send any patches I
created? Would this list be appropriate?
I hope you find this patch useful.
Regards,
Nicholas
Index: Doxyfile
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/ecore/Doxyfile,v
retrieving revision 1.2
diff -u -r1.2 Doxyfile
--- Doxyfile 23 Sep 2003 08:09:19 -0000 1.2
+++ Doxyfile 24 Apr 2004 10:34:53 -0000
@@ -1,7 +1,7 @@
PROJECT_NAME = Ecore
PROJECT_NUMBER =
OUTPUT_DIRECTORY = doc
-INPUT = ecore.c
+INPUT = ecore.c.in ./src/lib
IMAGE_PATH = doc/img
OUTPUT_LANGUAGE = English
GENERATE_HTML = YES
@@ -63,7 +63,7 @@
WARN_FORMAT = "$file:$line: $text"
WARN_LOGFILE =
FILE_PATTERNS =
-RECURSIVE = NO
+RECURSIVE = YES
EXCLUDE =
EXCLUDE_SYMLINKS = NO
EXCLUDE_PATTERNS =
Index: ecore.c.in
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/ecore/ecore.c.in,v
retrieving revision 1.4
diff -u -r1.4 ecore.c.in
--- ecore.c.in 20 Feb 2004 08:18:28 -0000 1.4
+++ ecore.c.in 24 Apr 2004 10:34:54 -0000
@@ -1,5 +1,4 @@
/**
[EMAIL PROTECTED]
@brief Ecore Library Public API Calls
These routines are used for Ecore Library interaction
Index: gendoc
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/ecore/gendoc,v
retrieving revision 1.3
diff -u -r1.3 gendoc
--- gendoc 16 Feb 2004 02:48:13 -0000 1.3
+++ gendoc 24 Apr 2004 10:34:54 -0000
@@ -1,11 +1,4 @@
#!/bin/sh
-cp ./ecore.c.in ./ecore.c
-for I in `find ./src/lib -name "Ecore*.h" -print`; do
- cat $I >> ./ecore.c
-done
-for I in `find ./src/lib -name "*.c" -print`; do
- cat $I >> ./ecore.c
-done
rm -rf ./doc/html ./doc/latex ./doc/man
doxygen
cp doc/img/*.png doc/html/
Index: src/lib/ecore/Ecore.h
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/ecore/src/lib/ecore/Ecore.h,v
retrieving revision 1.11
diff -u -r1.11 Ecore.h
--- src/lib/ecore/Ecore.h 14 Apr 2004 08:51:18 -0000 1.11
+++ src/lib/ecore/Ecore.h 24 Apr 2004 10:34:56 -0000
@@ -1,6 +1,13 @@
#ifndef _ECORE_H
#define _ECORE_H
+/**
+ * @file Ecore.h
+ * @brief The file that provides the program utility, main loop and timer
+ * functions.
+ *
+ */
+
#include <sys/types.h>
#include <unistd.h>
#include <stdio.h>
Index: src/lib/ecore/Ecore_Data.h
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/ecore/src/lib/ecore/Ecore_Data.h,v
retrieving revision 1.3
diff -u -r1.3 Ecore_Data.h
--- src/lib/ecore/Ecore_Data.h 18 Mar 2004 20:56:20 -0000 1.3
+++ src/lib/ecore/Ecore_Data.h 24 Apr 2004 10:34:58 -0000
@@ -1,6 +1,11 @@
#ifndef _ECORE_DATA_H
#define _ECORE_DATA_H
+/**
+ * @file Ecore_Data.h
+ * @brief Contains threading, list, hash, debugging and tree functions.
+ */
+
#define PRIME_TABLE_MAX 21
#define PRIME_MIN 17
#define PRIME_MAX 16777213
Index: src/lib/ecore_con/Ecore_Con.h.in
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/ecore/src/lib/ecore_con/Ecore_Con.h.in,v
retrieving revision 1.1
diff -u -r1.1 Ecore_Con.h.in
--- src/lib/ecore_con/Ecore_Con.h.in 31 Mar 2004 16:47:45 -0000 1.1
+++ src/lib/ecore_con/Ecore_Con.h.in 24 Apr 2004 10:35:12 -0000
@@ -1,6 +1,11 @@
#ifndef _ECORE_CON_H
#define _ECORE_CON_H
+/**
+ * @file Ecore_Con.h
+ * @brief Sockets functions.
+ */
+
#define HAVE_ECORE_CON_OPENSSL @USE_OPENSSL@
#if HAVE_ECORE_CON_OPENSSL
Index: src/lib/ecore_config/Ecore_Config.h
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/ecore/src/lib/ecore_config/Ecore_Config.h,v
retrieving revision 1.16
diff -u -r1.16 Ecore_Config.h
--- src/lib/ecore_config/Ecore_Config.h 22 Apr 2004 23:38:19 -0000 1.16
+++ src/lib/ecore_config/Ecore_Config.h 24 Apr 2004 10:35:12 -0000
@@ -2,25 +2,16 @@
#define _ECORE_CONFIG_H
/**
- * @file Ecore_Config.h
- * @brief The file that any project using ecore_config will want to include.
- *
- * This file provies all headers and structs for use with Ecore_Config.
- * Using individual header files should not be necessary.
- */
-
-/**
- * @mainpage Enlightened Configuration Library Documentation
- *
- * @image html ecore_config_mini.png
- *
- * @section intro Introduction
+ * @file
+ * @brief Provides 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.
+ *
+ * This file provies all headers and structs for use with Ecore_Config.
+ * Using individual header files should not be necessary.
*/
-
#define DIR_DELIMITER '/'
#define ECORE_CONFIG_FLOAT_PRECISION 1000
Index: src/lib/ecore_evas/Ecore_Evas.h.in
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/ecore/src/lib/ecore_evas/Ecore_Evas.h.in,v
retrieving revision 1.1
diff -u -r1.1 Ecore_Evas.h.in
--- src/lib/ecore_evas/Ecore_Evas.h.in 3 Feb 2004 20:12:28 -0000 1.1
+++ src/lib/ecore_evas/Ecore_Evas.h.in 24 Apr 2004 10:35:12 -0000
@@ -1,6 +1,11 @@
#ifndef _ECORE_EVAS_H
#define _ECORE_EVAS_H
+/**
+ * @file Ecore_Evas.h
+ * @brief Evas wrapper functions
+ */
+
/* FIXME:
* to do soon:
* - iconfication api needs to work
Index: src/lib/ecore_fb/Ecore_Fb.h
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/ecore/src/lib/ecore_fb/Ecore_Fb.h,v
retrieving revision 1.2
diff -u -r1.2 Ecore_Fb.h
--- src/lib/ecore_fb/Ecore_Fb.h 23 Sep 2003 08:09:31 -0000 1.2
+++ src/lib/ecore_fb/Ecore_Fb.h 24 Apr 2004 10:35:12 -0000
@@ -1,6 +1,11 @@
#ifndef _ECORE_FB_H
#define _ECORE_FB_H
+/**
+ * @file
+ * @brief Ecore frame buffer system functions.
+ */
+
/* FIXME:
* maybe a new module?
* - code to get battery info
Index: src/lib/ecore_ipc/Ecore_Ipc.h.in
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/ecore/src/lib/ecore_ipc/Ecore_Ipc.h.in,v
retrieving revision 1.1
diff -u -r1.1 Ecore_Ipc.h.in
--- src/lib/ecore_ipc/Ecore_Ipc.h.in 6 Apr 2004 06:20:39 -0000 1.1
+++ src/lib/ecore_ipc/Ecore_Ipc.h.in 24 Apr 2004 10:35:12 -0000
@@ -1,6 +1,11 @@
#ifndef _ECORE_IPC_H
#define _ECORE_IPC_H
+/**
+ * @file Ecore_Ipc.h
+ * @brief Ecore inter-process communication functions.
+ */
+
#define HAVE_ECORE_IPC_OPENSSL @USE_OPENSSL@
#if HAVE_ECORE_IPC_OPENSSL
Index: src/lib/ecore_job/Ecore_Job.h
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/ecore/src/lib/ecore_job/Ecore_Job.h,v
retrieving revision 1.2
diff -u -r1.2 Ecore_Job.h
--- src/lib/ecore_job/Ecore_Job.h 23 Sep 2003 08:09:31 -0000 1.2
+++ src/lib/ecore_job/Ecore_Job.h 24 Apr 2004 10:35:12 -0000
@@ -1,6 +1,11 @@
#ifndef _ECORE_JOB_H
#define _ECORE_JOB_H
+/**
+ * @file
+ * @brief Functions for dealing with Ecore jobs.
+ */
+
#ifdef __cplusplus
extern "C" {
#endif
Index: src/lib/ecore_txt/Ecore_Txt.h
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/ecore/src/lib/ecore_txt/Ecore_Txt.h,v
retrieving revision 1.1
diff -u -r1.1 Ecore_Txt.h
--- src/lib/ecore_txt/Ecore_Txt.h 9 Oct 2003 07:49:59 -0000 1.1
+++ src/lib/ecore_txt/Ecore_Txt.h 24 Apr 2004 10:35:12 -0000
@@ -1,6 +1,11 @@
#ifndef _ECORE_TXT_H
#define _ECORE_TXT_H
+/**
+ * @file Ecore_Txt.h
+ * @brief Provides a text encoding conversion function.
+ */
+
#ifdef __cplusplus
extern "C" {
#endif
Index: src/lib/ecore_x/Ecore_X.h
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/ecore/src/lib/ecore_x/Ecore_X.h,v
retrieving revision 1.44
diff -u -r1.44 Ecore_X.h
--- src/lib/ecore_x/Ecore_X.h 23 Apr 2004 22:48:20 -0000 1.44
+++ src/lib/ecore_x/Ecore_X.h 24 Apr 2004 10:35:12 -0000
@@ -1,6 +1,11 @@
#ifndef _ECORE_X_H
#define _ECORE_X_H
+/**
+ * @file
+ * @brief Ecore functions for dealing with the X Windows system
+ */
+
typedef unsigned int Ecore_X_ID;
#ifndef _ECORE_X_WINDOW_PREDEF
typedef Ecore_X_ID Ecore_X_Window;
Index: src/lib/ecore_x/Ecore_X_Cursor.h
===================================================================
RCS file: /cvsroot/enlightenment/e17/libs/ecore/src/lib/ecore_x/Ecore_X_Cursor.h,v
retrieving revision 1.1
diff -u -r1.1 Ecore_X_Cursor.h
--- src/lib/ecore_x/Ecore_X_Cursor.h 22 Jan 2004 23:13:50 -0000 1.1
+++ src/lib/ecore_x/Ecore_X_Cursor.h 24 Apr 2004 10:35:12 -0000
@@ -1,6 +1,11 @@
#ifndef _ECORE_X_CURSOR_H
#define _ECORE_X_CURSOR_H
+/**
+ * @file
+ * @brief Defines the various cursor types for the X Windows system.
+ */
+
#define ECORE_X_CURSOR_X 0
#define ECORE_X_CURSOR_ARROW 2
#define ECORE_X_CURSOR_BASED_ARROW_DOWN 4
