Commit d217f68a authored by Matthias Braun's avatar Matthias Braun
Browse files

Added missing API docu, improved existing API docu

Now every bit in the public API is documented so we can enable doxygen
warnings for undocumented members.
parent 9ba38e71
......@@ -38,7 +38,7 @@ PROJECT_NUMBER =
# If a relative path is entered, it will be relative to the location
# where doxygen was started. If left blank the current directory will be used.
OUTPUT_DIRECTORY = ./firm-doc
OUTPUT_DIRECTORY = build/firm-doc
# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create
# 4096 sub-directories (in 2 levels) under the output directory of each output
......@@ -245,7 +245,7 @@ SIP_SUPPORT = NO
# setting a simple type. If this is not the case, or you want to show the
# methods anyway, you should set this option to NO.
IDL_PROPERTY_SUPPORT = YES
IDL_PROPERTY_SUPPORT = NO
# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC
# tag is set to YES, then doxygen will reuse the documentation of the first
......@@ -286,7 +286,7 @@ TYPEDEF_HIDES_STRUCT = YES
# 2^(16+SYMBOL_CACHE_SIZE). The valid range is 0..9, the default is 0,
# corresponding to a cache size of 2^16 = 65536 symbols
SYMBOL_CACHE_SIZE = 0
SYMBOL_CACHE_SIZE = 2
#---------------------------------------------------------------------------
# Build related configuration options
......@@ -297,7 +297,7 @@ SYMBOL_CACHE_SIZE = 0
# Private class members and static file members will be hidden unless
# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES
EXTRACT_ALL = yes
EXTRACT_ALL = no
# If the EXTRACT_PRIVATE tag is set to YES all private members of a class
# will be included in the documentation.
......@@ -307,7 +307,7 @@ EXTRACT_PRIVATE = no
# If the EXTRACT_STATIC tag is set to YES all static members of a file
# will be included in the documentation.
EXTRACT_STATIC = NO
EXTRACT_STATIC = YES
# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs)
# defined locally in source files will be included in the documentation.
......@@ -527,7 +527,7 @@ WARNINGS = YES
# for undocumented members. If EXTRACT_ALL is set to YES then this flag will
# automatically be disabled.
WARN_IF_UNDOCUMENTED = NO
WARN_IF_UNDOCUMENTED = YES
# If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for
# potential errors in the documentation, such as not documenting some
......@@ -557,7 +557,7 @@ WARN_FORMAT = "$file:$line: $text"
# and error messages should be written. If left blank the output is written
# to stderr.
WARN_LOGFILE = ./firm-doc/warnings
WARN_LOGFILE =
#---------------------------------------------------------------------------
# configuration options related to the input files
......@@ -1302,7 +1302,7 @@ TAGFILES =
# When a file name is specified after GENERATE_TAGFILE, doxygen will create
# a tag file that is based on the input files it reads.
GENERATE_TAGFILE = firm-doc/libfirm.tag
GENERATE_TAGFILE = build/firm-doc/libfirm.tag
# If the ALLEXTERNALS tag is set to YES all external classes will be listed
# in the class index. If set to NO only the inherited external classes
......
......@@ -14,6 +14,7 @@ variant ?= debug
srcdir ?= $(top_srcdir)
builddir ?= $(top_builddir)/$(variant)
docdir ?= $(top_builddir)/firm-doc
# This hides the noisy commandline outputs. You can see them with "make Q="
Q ?= @
......@@ -177,18 +178,18 @@ $(builddir)/%.o: %.c $(IR_SPEC_GENERATED_FILES) config.h
@echo CC $@
$(Q)$(CC) $(CFLAGS) $(CPPFLAGS) $(libfirm_CPPFLAGS) -MMD -c -o $@ $<
firm-doc/libfirm.tag: $(IR_SPEC_GENERATED_FILES) Doxyfile $(wildcard include/libfirm/*.h) $(wildcard include/libfirm/adt/*.h)
$(docdir)/libfirm.tag: $(IR_SPEC_GENERATED_FILES) Doxyfile $(wildcard include/libfirm/*.h) $(wildcard include/libfirm/adt/*.h)
@echo Doxygen
$(Q)$(DOXYGEN)
DOCU_GENERATOR := scripts/gen_docu.py
firm-doc/html/nodes.html: firm-doc/libfirm.tag $(DOCU_GENERATOR) $(IR_SPEC) scripts/spec_util.py scripts/style.css
$(docdir)/html/nodes.html: $(docdir)/libfirm.tag $(DOCU_GENERATOR) $(IR_SPEC) scripts/spec_util.py scripts/style.css
@echo gen_docu.py
$(Q)$(DOCU_GENERATOR) firm-doc/libfirm.tag "" $@
$(Q)cp scripts/style.css firm-doc/html
$(Q)$(DOCU_GENERATOR) $(docdir)/libfirm.tag "" $@
$(Q)cp scripts/style.css $(docdir)/html
.PHONY: documentation
documentation: firm-doc/libfirm.tag firm-doc/html/nodes.html
documentation: $(docdir)/libfirm.tag $(docdir)/html/nodes.html
.PHONY: clean
clean:
......@@ -196,4 +197,3 @@ clean:
$(Q)rm -f $(libfirm_OBJECTS)
$(Q)rm -f $(libfirm_TARGET)
$(Q)rm -f $(shell find ir/ -name "gen_*.[ch]")
$(Q)rm -rf firm-docu
libFirm 1.19.1 (2011-05-17)
---------------------------
* Fix some set_XXX functions not being exported in the shared library
libFirm 1.19.0 (2011-03-15)
---------------------------
......
......@@ -32,6 +32,12 @@
#include "../begin.h"
/**
* @ingroup adt
* @defgroup array Arrays
* @{
*/
/**
* Creates a flexible array.
*
......@@ -209,11 +215,15 @@
# define ARR_VRFY(arr) ((void)0)
# define ARR_IDX_VRFY(arr, idx) ((void)0)
#else
/** Check array for consistency */
# define ARR_VRFY(arr) ir_verify_arr(arr)
/** Check if index is within array bounds */
# define ARR_IDX_VRFY(arr, idx) \
assert((0 <= (idx)) && ((idx) < ARR_LEN((arr))))
#endif
/** @cond PRIVATE */
/** A type that has most constrained alignment. */
typedef union {
long double d;
......@@ -221,7 +231,6 @@ typedef union {
long l;
} aligned_type;
/**
* The array descriptor header type.
*/
......@@ -257,6 +266,10 @@ static inline void ARR_SHRINKLEN(void *arr, size_t new_len)
ARR_DESCR(arr)->nelts = new_len;
}
/** @endcond */
/** @} */
#include "../end.h"
#endif
......@@ -28,13 +28,30 @@
#include "../begin.h"
/**
* @ingroup algorithms
* @defgroup bipartite Bipartite Matching
* Solved bipartite matching problem.
* (Variant with only 0/1 costs)
* @{
*/
/** internal representation of bipartite matching problem */
typedef struct bipartite_t bipartite_t;
/** Create new bipartite matching problem with @p n_left elements on left side
* and @p n_right elements on right side */
FIRM_API bipartite_t *bipartite_new(int n_left, int n_right);
/** Free memory occupied by bipartite matching problem */
FIRM_API void bipartite_free(bipartite_t *gr);
/** Add edge from @p i (on the left side) to @p j (on the right side) */
FIRM_API void bipartite_add(bipartite_t *gr, int i, int j);
/** Remove edge from @p i (on the left side) to @p j (on the right side) */
FIRM_API void bipartite_remv(bipartite_t *gr, int i, int j);
/** Return 1 if edge from @p i (on the left side) to @p j (on the right side)
* exists, 0 otherwise */
FIRM_API int bipartite_adj(const bipartite_t *gr, int i, int j);
/** Solve bipartite matching problem */
FIRM_API void bipartite_matching(const bipartite_t *gr, int *matching);
/**
......@@ -47,6 +64,8 @@ FIRM_API void bipartite_dump_f(FILE *f, const bipartite_t *gr);
*/
FIRM_API void bipartite_dump(const char *name, const bipartite_t *gr);
/** @} */
#include "../end.h"
#endif /* _BIPARTITE_H */
......@@ -28,6 +28,13 @@
#include "../begin.h"
/**
* @ingroup adt
* @defgroup Pointer Set (custom Compare)
* A pointer set with user-definable compare function
* @{
*/
/**
* The type of a cpset compare function.
*
......@@ -43,6 +50,8 @@ typedef int (*cpset_cmp_function) (const void *p1, const void *p2);
*/
typedef unsigned (*cpset_hash_function) (const void *obj);
/** @cond PRIVATE */
#define HashSet cpset_t
#define HashSetIterator cpset_iterator_t
#define HashSetEntry cpset_hashset_entry_t
......@@ -55,7 +64,12 @@ typedef unsigned (*cpset_hash_function) (const void *obj);
#undef HashSetIterator
#undef HashSet
/** @endcond */
/** a pointer set with custom compare function */
typedef struct cpset_t cpset_t;
/** iterator over a pointer set with custom compare function
* @see #cpset_t */
typedef struct cpset_iterator_t cpset_iterator_t;
/**
......@@ -151,6 +165,8 @@ FIRM_API void *cpset_iterator_next(cpset_iterator_t *iterator);
*/
FIRM_API void cpset_remove_iterator(cpset_t *cpset, const cpset_iterator_t *iterator);
/** @} */
#include "../end.h"
#endif
......@@ -7,6 +7,13 @@
#include "../begin.h"
/**
* @ingroup algorithms
* @defgroup gassjordan Gauss Jordan Elimination
* Solves a system of linear equations
* @{
*/
/**
* solves a system of linear equations and returns 0 if successful
*
......@@ -16,6 +23,8 @@
*/
FIRM_API int firm_gaussjordansolve(double *A, double *b, int nsize);
/** @} */
#include "../end.h"
#endif
......@@ -19,7 +19,7 @@
/**
* @file
* @brief Hash function for pointers
* @brief Hash functions
* @author Michael Beck, Sebastian Hack
*/
#ifndef FIRM_ADT_HASHPTR_H
......@@ -28,12 +28,25 @@
#include <stdlib.h>
#include "../begin.h"
/**
* @ingroup algorithms
* @defgroup hashptr Hash Functions
* @{
*/
/** @cond DISABLED */
#define _FIRM_FNV_OFFSET_BASIS 2166136261U
#define _FIRM_FNV_FNV_PRIME 16777619U
/* Computing x * _FIRM_FNV_FNV_PRIME */
#define _FIRM_FNV_TIMES_PRIME(x) ((x) * _FIRM_FNV_FNV_PRIME)
/** @endcond */
/**
* Returns a hash value for a block of data.
*/
static inline unsigned hash_data(const unsigned char *data, size_t bytes)
{
size_t i;
......@@ -50,17 +63,16 @@ static inline unsigned hash_data(const unsigned char *data, size_t bytes)
/**
* Returns a hash value for a string.
* @param str The string (can be const).
* @param len The length of the string.
* @return A hash value for the string.
*/
static inline unsigned hash_str(const char *data)
static inline unsigned hash_str(const char *str)
{
unsigned i;
unsigned hash = _FIRM_FNV_OFFSET_BASIS;
for(i = 0; data[i] != '\0'; ++i) {
for(i = 0; str[i] != '\0'; ++i) {
hash = _FIRM_FNV_TIMES_PRIME(hash);
hash ^= data[i];
hash ^= str[i];
}
return hash;
......@@ -78,9 +90,9 @@ static inline unsigned hash_ptr(const void *ptr)
/**
* Combines 2 hash values.
* @param a One hash value.
* @param b Another hash value.
* @return A hash value computed from both.
* @param x One hash value.
* @param y Another hash value.
* @return A hash value computed from both.
*/
static inline unsigned hash_combine(unsigned x, unsigned y)
{
......@@ -91,6 +103,8 @@ static inline unsigned hash_combine(unsigned x, unsigned y)
return hash;
}
/** @} */
#include "../end.h"
#endif
......@@ -34,17 +34,29 @@
#include "../begin.h"
/**
* @ingroup algorithms
* @defgroup hungarian Hungarian Algorithm
* Solves bipartite matching problems (minimize/maximize cost function)
* @{
*/
/** type of matching */
typedef enum match_type_t {
HUNGARIAN_MATCH_NORMAL, /**< ever nodes matches another node */
HUNGARIAN_MATCH_PERFECT /**< matchings of nodes having no edge getting
removed */
} match_type_t;
/** mode of matching (the optimization goal) */
typedef enum hungarian_mode_t {
HUNGARIAN_MODE_MINIMIZE_COST,
HUNGARIAN_MODE_MAXIMIZE_UTIL
HUNGARIAN_MODE_MINIMIZE_COST, /**< minimize cost */
HUNGARIAN_MODE_MAXIMIZE_UTIL /**< maximize cost */
} hungarian_mode_t;
/**
* Internal representation of a bipartite matching problem
*/
typedef struct hungarian_problem_t hungarian_problem_t;
/**
......@@ -105,6 +117,8 @@ FIRM_API int hungarian_solve(hungarian_problem_t *p, unsigned *assignment,
FIRM_API void hungarian_print_cost_matrix(hungarian_problem_t *p,
int cost_width);
/** @} */
#include "../end.h"
#endif
#ifndef FIRM_ADT_LIST_H
#define FIRM_ADT_LIST_H
#include <stdlib.h>
#include "../begin.h"
/**
* @file
* @ingroup adt
* @defgroup lists Linked Lists
* @brief Doubly linked lists.
*
* Simple doubly linked list implementation.
......@@ -9,36 +17,41 @@
* sometimes we already know the next/prev entries and we can
* generate better code by using them directly rather than
* using the generic single-entry routines.
*/
#ifndef FIRM_ADT_LIST_H
#define FIRM_ADT_LIST_H
#include <stdlib.h>
#include "../begin.h"
* @{
*/
/**
* List Header.
* Put this into all list elements and at the place where you want to keep
* references to the list. */
typedef struct list_head list_head;
struct list_head {
struct list_head *next, *prev;
};
/** Static initializer for a list header */
#define LIST_HEAD_INIT(name) { &(name), &(name) }
/** Defines a (static) list reference */
#define LIST_HEAD(name) \
struct list_head name = LIST_HEAD_INIT(name)
/** Initializes a list header */
#define INIT_LIST_HEAD(ptr) do { \
(ptr)->next = (ptr); (ptr)->prev = (ptr); \
} while (0)
/** @cond PRIVATE */
struct list_head {
struct list_head *next, *prev;
};
#define _list_offsetof(type,member) \
((char *) &(((type *) 0)->member) - (char *) 0)
#define _list_container_of(ptr, type, member) \
((type *) ((char *) (ptr) - _list_offsetof(type, member)))
/** @endcond */
/*
* Insert a new entry between two known consecutive entries.
/**
* Inserts a new entry between two known consecutive entries.
*
* This is only for internal list manipulation where we know
* the prev/next entries already!
......@@ -54,7 +67,7 @@ static inline void __list_add(struct list_head *new_node,
}
/**
* list_add - add a new entry
* Adds a new entry
* @param new_node new entry to be added
* @param head list head to add it after
*
......@@ -67,7 +80,7 @@ static inline void list_add(struct list_head *new_node, struct list_head *head)
}
/**
* list_add_tail - add a new entry
* Adds a new entry
* @param new_node new entry to be added
* @param head list head to add it before
*
......@@ -79,8 +92,8 @@ static inline void list_add_tail(struct list_head *new_node, struct list_head *h
__list_add(new_node, head->prev, head);
}
/*
* Delete a list entry by making the prev/next entries
/**
* Deletes a list entry by making the prev/next entries
* point to each other.
*
* This is only for internal list manipulation where we know
......@@ -93,7 +106,7 @@ static inline void __list_del(struct list_head * prev, struct list_head * next)
}
/**
* list_del - deletes entry from list.
* Deletes entry from list.
* @param entry the element to delete from the list.
*
* @note
......@@ -109,7 +122,7 @@ static inline void list_del(struct list_head *entry)
/**
* list_del_init - deletes entry from list and reinitialize it.
* Deletes entry from list and reinitialize it.
* @param entry the element to delete from the list.
*/
static inline void list_del_init(struct list_head *entry)
......@@ -119,7 +132,7 @@ static inline void list_del_init(struct list_head *entry)
}
/**
* list_move - delete from one list and add as another's head
* Deletes from one list and add as another's head
* @param list the entry to move
* @param head the head that will precede our entry
*/
......@@ -130,7 +143,7 @@ static inline void list_move(struct list_head *list, struct list_head *head)
}
/**
* list_move_tail - delete from one list and add as another's tail
* Deletes from one list and add as another's tail
* @param list the entry to move
* @param head the head that will follow our entry
*/
......@@ -142,7 +155,7 @@ static inline void list_move_tail(struct list_head *list,
}
/**
* list_empty - tests whether a list is empty
* Tests whether a list is empty
* @param head the list to test.
*/
static inline int list_empty(const struct list_head *head)
......@@ -150,6 +163,13 @@ static inline int list_empty(const struct list_head *head)
return head->next == head;
}
/**
* Join two nonempty lists.
*
* @note Use list_splice() if @p list is possibly empty.
* @param list the new list to add.
* @param head the place to add it in the first list.
*/
static inline void __list_splice(struct list_head *list,
struct list_head *head)
{
......@@ -278,6 +298,8 @@ static inline void list_splice_init(struct list_head *list,
&pos->member != (head); \
pos = n, n = list_entry(n->member.next, type, member))
/** @} */
#include "../end.h"
#endif
......@@ -19,7 +19,7 @@
/**
* @file
* @brief Provied obstack_chunk_alloc and obstack_chunk_free for obstack.h
* @brief Provides obstack_chunk_alloc and obstack_chunk_free for obstack.h
* @author Martin Trapp, Christian Schaefer
*/
#ifndef FIRM_ADT_OBST_H
......@@ -28,9 +28,13 @@
#include "obstack.h"
#include "xmalloc.h"
/** @cond PRIVATE */
#define obstack_chunk_alloc xmalloc
#define obstack_chunk_free free
/** @endcond */
/** An obstack initializer containing zero values. Can be used to initialize
* obstacks in an initializer. */
#define NULL_OBST { 0, NULL, NULL, NULL, NULL, 0, 0, NULL, NULL, NULL, 0, 0, 0 }
#endif
......@@ -18,6 +18,18 @@
Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
Boston, MA 02110-1301, USA. */
/** @page obstack Obstack Memory Allocation
*
* Obstacks are the prefered way to handle memory allocation in libFirm.
* Compared to classical malloc they are faster but don't allow fine-grained
* freeing of allocated memory. But in a compile this is fine most of the time
* as memory is allocated for a phase or a graph and later the whole phase ends
* or the whole graph gets discarded.
*
* There's very good documentation about Object stacks in the glibc manual:
* http://www.gnu.org/s/libc/manual/html_node/Obstacks.html
*/
/* Summary:
All the apparent functions defined here are macros. The idea
......@@ -108,6 +120,8 @@ Summary:
#include "../begin.h"
/** @cond DISABLED */
/* We need the type of a pointer subtraction. If __PTRDIFF_TYPE__ is
defined, as with GNU C, use that; that way we don't pollute the
namespace with <stddef.h>'s symbols. Otherwise, include <stddef.h>
......@@ -530,6 +544,8 @@ int obstack_printf(struct obstack *obst, const char *fmt, ...)
int obstack_vprintf(struct obstack *obst, const char *fmt, va_list ap)
FIRM_NOTHROW FIRM_PRINTF(2, 0);
/** @endcond */
#include "../end.h"
#endif
......@@ -29,6 +29,13 @@
#include "../begin.h"
/**
* @ingroup adt
* @defgroup pdeq Double Ended Queue
* Implementation if a double ended queue datastructure for generic pointers
* @{
*/
/**
* The type of the pointer compare function.
*
......@@ -264,6 +271,8 @@ typedef pdeq stack;
*/
#define stack_empty(st) pdeq_empty(wq)
/** @} */
#include "../end.h"
#endif
......@@ -26,9 +26,6 @@
* not very well suited for the interference graph implementation.
* This list uses an obstack and a free-list to efficiently manage its
* elements.
* @note Until now the code is entirely untested so it probably contains
* plenty of errors. (Matze: Is this still true, the code seems to be
* used at some places....)
* @deprecated
*/
#ifndef FIRM_ADT_PLIST_H
......@@ -46,27 +43,19 @@ typedef struct plist plist_t;
* The plist data type.
*/
struct plist {
/**
* The obstack used for all allocations.
*/
/** The obstack used for all allocations. */
struct obstack *obst;
/* Set to 1 if plist uses a foreign obstack */