docs: collect commit messages #1

Up to (and including) commit b6a32fb8
'fixing bugs (static code analysis)'

docs/commit_messages.txt

 
+Toplevel files:
+
+sefht.geany:
+	For developing I use the IDE Geany. This file contains the
+	project description as well as all open files. It is included
+	in the VCS, because it is practical to have the position where
+	it was last worked on when switching branches. However this
+	file also often creates merge conflicts, which could be avoided,
+	if this file was not tracked by the VCS.
+
+configure.ac:
+	This package uses the GNU Autotools.
+
+main.c:
+	As this project is about a library, a main.c would not be
+	expected. It contains a small demo program using the library.
+
+todo.txt:
+	Contains features, that are discovered to be needed,
+	but aren't yet implemented.
+
+
+General:
+Error handling:
+	Error handling is done by passing an Error structure as an
+	inout parameter to functions that can fail on runtime
+	predictably. This parameter is always the last one. Methods,
+	where there is no error, that can be detected on runtime,
+	don't have an error parameter.
+	When an Error is detected, also an ERROR is passed to the log.
+	Because this isn't implemented yet, it is replaced by a call
+	to printf.
+	Some may argue, that in case of a fatal error, like if no memory
+	can be allocated, a program should just give up and crash.
+	However this behaviour is not very user-friendly.
+	There might be some cases, where it does not make sense or
+	it isn't possible to provide the user with some opportunity to
+	e.g. save a file. But it is not decidable in a library,
+	whether there is an option to inform the user, something must
+	be cleaned up or even that recovering is possible at all.
+	A lot of these recognized errors are a failing malloc or an
+	over-/underflow.
+
+	Error handling can be ignored by the caller by passing NULL to
+	the Error parameter. Whether an error had occurred, is also
+	always possible to be determined, by examining the return
+	value. [citation needed]
+	If the error occurs in a function returning a pointer, NULL will
+	be returned. If it returns a value, a special error value of
+	that type is returned, i.e. PAGE_ERR in SH_Data_register_page.
+	If the return type would be void otherwise, a boolean is
+	returned, which tells, whether the method has succeeded.
+	(FALSE means, that an error has occurred.)
+
+	The error may have occurred in an internal method and is passed
+	upwards (the stack).
+	Internally, errors are handled by an enum, but this must be
+	considered an implementation detail and can be changed in later
+	versions.
+	It is in the responsibility of the caller to recover gracefully.
+	It has to be assumed that the requested operation have neither
+	worked, nor actually took place.  [citation needed]
+	Those the operation can be retried (hopefully).
+
+Classes:
+CMS:
+	This class bundles some features and might be the entry point
+	of the library in the future. At the moment it doesn't do much.
+	- Pages are hold by Data, CMS passes trough the call(s).
+
+Data:
+	This class will handle Data needed by the CMS, provides storage
+	for modules, manages the database connection and maybe also
+	contains some caches. At the moment it only provides access to
+	the Validator.
+
+Fragment:
+	Fragment is the core of SeFHT. (As the name suggests)
+	It represents a Node inside the DOM and all subsequent
+	Nodes (a Tree).
+	A Fragment can contain childs. When building the html, the
+	childs html is generated where appropiate.
+	The methods
+	- SH_Fragment_get_child (by index)
+	- SH_Fragment_is_child (non recursive) and
+	- SH_Fragment_is_descendant (recursive)
+	were added.
+	Fragment can be copied, either recursive (copying also all
+	childs) or nonrecursive (ignoring the childs, thus the copy
+	has always no childs).
+	Adding the same element twice in the tree (graph) isn't
+	possible, as this would lead to problems e.g. double free or
+	similar quirks.
+	A Fragment can output it's html. If there is an error the method
+	aborts and returns NULL.
+	When the wrap mode is used, after each tag a newline is started.
+	Also the html is indented, which can be configured by the
+	parameters indent_base, indent_step and indent_char. The
+	parameter indent_base specifies the width the first tag should
+	be indented with, while indent_step specifies the increment of
+	the indent when switching to a child tag. The character, that is
+	used for indenting is taken from indent_char. (It could also be
+	a string longer than a single character).
+	This arguments can't be set by the user, but are hardcoded
+	(by now).
+
+Validator:
+	Validator serves as an syntax checker, i.e. it can be requested
+	whether a tag is allowed.
+	On initialization (of data), the Validator's knowledge is filled
+	with some common tags. This is of course to be replaced later,
+	by some dynamic handling.
+	When a tag is made known to the Validator, which it already
+	knows, the old id is returned and nothing is added.
+
+Text:
+	This is a data type to deal with frequently appending to a string.
+	The space a Text has for saving the string is allocated in chunks.
+	To request additional space SH_Text_enlarge is called. If the
+	requested size fits inside the already allocated space or is even
+	smaller than the current size, nothing is done. Otherwise a
+	multiple of chunk size is allocated beeing equal or greater than
+	the requested size. The chunk size can be changed by changing
+	the macro CHUNK_SIZE in src/text.h. The default is 64.
+	The adjustment is done automatically when a string is added.
+	SH_Text_append_string can be used to append a string to the text,
+	SH_Text_append_text can be used to append another text to the text.
+	SH_Text_join is a wrapper for SH_Text_append_text, but also frees
+	the second text, thus joining the texts to a single one.
+
+
+Tests:
+	Tests are done using check, allowing to integrate the tests
+	into the GNU Autotools.
+	Methods that are part of another unit, but are called in a unit
+	aren't tested as this would interfere with the idea of unittests.
+	This applies for purely wrapper functions, where a call is just
+	passed to another unit.
+	Because sometimes an overflow condition is checked, it is
+	necessary to include the sourcefile into the test, instead of
+	linking against the objectfile. This also allows for the
+	separate testing of static functions, as the static keyword
+	can be overridden with an empty macro.
+	Sometimes it isn't possible to check for correct overflow
+	detection by setting some number to ..._MAX, because this
+	number is used, thus a SIGSEGV would be raised. This is solved
+	by filling garbage until ..._MAX is really reached. Because
+	there is a timeout for the tests and it would fill RAM with
+	gigabytes of garbage, ..._MAX is overridden prior to inclusion
+	of the sourcefile.
+
+TODO:
+Log:
+	It is useful for debugging to actually see the error messages.

sefht.geany

@@ -34,7 +34,7 @@ FILE_NAME_1=134;None;0;EUTF-8;1;1;0;%2Fhome%2Fjonathan%2FDokumente%2Fprojekte%2F
 FILE_NAME_2=1737;Sh;0;EUTF-8;1;1;0;%2Fhome%2Fjonathan%2FDokumente%2Fprojekte%2Fprgm%2Finternet%2Fweb%2FSeFHT%2Fconfigure.ac;0;8
 FILE_NAME_3=73;Make;0;EUTF-8;1;1;0;%2Fhome%2Fjonathan%2FDokumente%2Fprojekte%2Fprgm%2Finternet%2Fweb%2FSeFHT%2Fsrc%2FMakefile.am;0;8
 FILE_NAME_4=19;C;0;EUTF-8;1;1;0;%2Fhome%2Fjonathan%2FDokumente%2Fprojekte%2Fprgm%2Finternet%2Fweb%2FSeFHT%2Fsrc%2Fmain.c;0;8
-FILE_NAME_5=0;None;0;EUTF-8;1;1;0;%2Fhome%2Fjonathan%2FDokumente%2Fprojekte%2Fprgm%2Finternet%2Fweb%2FSeFHT%2Fdocs%2Fcommit_messages.txt;0;8
+FILE_NAME_5=4740;None;0;EUTF-8;1;1;0;%2Fhome%2Fjonathan%2FDokumente%2Fprojekte%2Fprgm%2Finternet%2Fweb%2FSeFHT%2Fdocs%2Fcommit_messages.txt;0;8
 FILE_NAME_6=1867;Make;0;EUTF-8;1;1;0;%2Fhome%2Fjonathan%2FDokumente%2Fprojekte%2Fprgm%2Finternet%2Fweb%2FSeFHT%2Fsrc%2Flib%2FMakefile.am;0;8
 FILE_NAME_7=18;C;0;EUTF-8;1;1;0;%2Fhome%2Fjonathan%2FDokumente%2Fprojekte%2Fprgm%2Finternet%2Fweb%2FSeFHT%2Fsrc%2Flib%2Fsefht%2Fcms.c;0;8
 FILE_NAME_8=18;C;0;EUTF-8;1;1;0;%2Fhome%2Fjonathan%2FDokumente%2Fprojekte%2Fprgm%2Finternet%2Fweb%2FSeFHT%2Fsrc%2Flib%2Fsefht%2Fcms.h;0;8