docs: collect commit messages #2

Up to (and including) commit f86bd5cf
'setup library (make & API)'

docs/commit_messages.txt

@@ -22,6 +22,28 @@ todo.txt:
 
 
 General:
+Compilation:
+	For compilation make is used.
+	The project implements a library and a small demo program,
+	which depends on the library.
+	For compiling and linking libtool is used, this way it also
+	supports both static and dynamic linking.
+	When compiling only the central header file can be included,
+	which takes care of including the other header files in the
+	right order. To prevent accidental inclusion, there are header
+	inclusion guards. If you need to include special stuff and also
+	depend on the internals, which is discouraged, the macro
+	SEFHT_COMPILATION has to be defined. This is also done, when
+	compiling the library itself, but also for compiling the tests,
+	as they also test a lot of implementation details. This is
+	needed, to distinguish a proper working function from a function
+	just pretending and doing nothing, or worse a function, that
+	results in corrupt data, which might not be detected by calling
+	other exported methods, which might not fail, or are themselves
+	buggy. Testing the later would defy the concept of unittests.
+	Thus, the easiest way to test for a proper working function,
+	is to test for the internal state.
+
 Error handling:
 	Error handling is done by passing an Error structure as an
 	inout parameter to functions that can fail on runtime
@@ -63,6 +85,11 @@ Error handling:
 	worked, nor actually took place.  [citation needed]
 	Those the operation can be retried (hopefully).
 
+splint:
+	The source has been adapted to splint, which still tells about some
+	errors, but they are all checked to be false-positives.
+
+
 Classes:
 CMS:
 	This class bundles some features and might be the entry point
@@ -77,8 +104,35 @@ Data:
 
 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 be every part of a website. The website is
+	handled as a tree (like the DOM, but this library doesn't
+	implement the DOM, it only resembles it, as this is the way,
+	HTML works).
+	There are several different types of Fragments. It is
+	represented by an abstract base class Fragment, which contains
+	some methods and attributes, which are supported by every type
+	of fragment. But the main functionality of the base class is,
+	to support inheritance. For this, it contains the type of
+	fragment, represented by an enum, and a virtual method table,
+	represented by a structure of function pointers.
+	The data needed by a fragment is, a pointer to the Data object,
+	which is needed for getting any kind of information a fragment
+	might need, and a pointer to the parent node, which is needed
+	both for access to it and also to ensure, that each fragment
+	has exactly one parent. This is necessary to prevent data
+	corruption and also to keep clear who is responsible, for
+	freeing the fragment.
+	The methods each fragment has to be implement are a copy method,
+	a free method (destructor) and a method to output the html.
+	Also every class has a method, which checks, if a given fragment
+	is of that type.
+	There are currently two types of fragments: Node and Text.
+	There is currently no forward compatibility for more types, but
+	this will be added. Also modules, might be partially implemented
+	by a different type of fragment.
+
+	The NodeFragment represents a html tag (like a Node in the DOM)
+	containing all its attributes and all subsequent Nodes (a Tree).
 	A Fragment can contain childs. When building the html, the
 	childs html is generated where appropiate.
 	The methods
@@ -116,19 +170,70 @@ Validator:
 
 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
+	multiple of chunk size is allocated being 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.
 
+	The constructor SH_Text_new_from_string accepts a string, with that the
+	text is initialized. This can replace the so far needed two calls
+	SH_Text_new and SH_Text_append_string.
+
+	The (intern) implementation of SH_Text was changed from an array of
+	char, to a single linked list of arrays of char. This allows an easier
+	implementation of (further) text manipulation.
+
+	The API hasn't changed much, but SH_Text_join can't yield an error
+	anymore, so it now doesn't support passing an error and returns nothing.
+	The method SH_Text_get_char returns a single character by a given index.
+	If the index is out of range, NULL is returned and error->type is set to
+	VALUE_ERROR.
+
+	The function SH_Text_get_string returns a substring of text beginning at
+	index and of length offset. If index is out of bounds, NULL is returned
+	and an error is set. If offset is out of bounds, the existent part is
+	returned. Also the length of the returned string can be set (optionally)
+	to the out parameter length.
+
+	If the original behaviour of SH_Text_get_string is achieved,
+	SH_Text_get_string (text, length, error) has to be changed to
+	SH_Text_get_string (text, 0, SIZE_MAX, length, error). The only
+	difference will be that the function won't fail, when the text is longer
+	than SIZE_MAX, because it is told to stop there. A text that is longer
+	than SIZE_MAX is not possible to be returned, but that wasn't possible
+	at anytime. Also I don't think handling char[] longer than SIZE_MAX is
+	possible with the standard C library. Those in this case the text can
+	only be returned in parts (By now only possible till 2*SIZE_MAX-1 with
+	calling SH_Text_get_string (text, SIZE_MAX, SIZE_MAX, length, error))
+	or has to be manipulated using the appropriate SH_Text methods, which are
+	not implemented yet.
+
+	The function SH_Text_get_range returns a string beginning at start and
+	ending at end. Note that end specifies the char, that is not returned
+	any more. Thus the function implements something similar, as the pythonic
+	slice syntax (text[start:end]). In opposition to the behaviour there,
+	calling SH_Text_get_range with start > end is undefined behaviour. If
+	start == end, the empty string is returned.
+	If start is out of bounds, NULL is returned and an error is set. If end
+	is out of bounds, the existent part is returned. Also the length of the
+	returned string can be set (optionally) to the out parameter length.
+	The function SH_Text_get_length returns the length of the text. As the
+	text also supports being longer than SIZE_MAX, this method can fail on
+	runtime. If the text is longer then SIZE_MAX, the Text returns SIZE_MAX
+	and sets error to DOMAIN_ERROR. Note, that due to the implementation,
+	this is a non trivial function, so don't use it to exhaustively.
+	The method SH_Text_print just prints the whole string to stdout.
+
 
 Tests:
 	Tests are done using check, allowing to integrate the tests

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=4740;None;0;EUTF-8;1;1;0;%2Fhome%2Fjonathan%2FDokumente%2Fprojekte%2Fprgm%2Finternet%2Fweb%2FSeFHT%2Fdocs%2Fcommit_messages.txt;0;8
+FILE_NAME_5=1831;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