From 8b92cc5369d8100dd2257698e00b9d1d3cdf3eee Mon Sep 17 00:00:00 2001 From: Anthony Arnold Date: Fri, 20 Jan 2012 11:20:42 +1000 Subject: [PATCH] Added documentation generated with AdaBrowse. When changing an interface, must run 'make docs' before commiting. --- Makefile | 9 +- doc/.gitignore | 0 doc/adaid-generate.html | 124 ++++++++++++++++ doc/adaid.html | 288 +++++++++++++++++++++++++++++++++++++ doc/index.html | 39 +++++ include/adaid-generate.ads | 18 ++- include/adaid.ads | 39 ++--- lib/.gitignore | 1 + 8 files changed, 493 insertions(+), 25 deletions(-) create mode 100644 doc/.gitignore create mode 100644 doc/adaid-generate.html create mode 100644 doc/adaid.html create mode 100644 doc/index.html diff --git a/Makefile b/Makefile index b1ccb2f..4a22555 100644 --- a/Makefile +++ b/Makefile @@ -11,7 +11,7 @@ MKDIR=mkdir -p CP=cp -.PHONY: debug test install installclean clean cleanall all support remove dist +.PHONY: debug test install installclean clean cleanall all support remove dist docs #library $(LIB): src/*.adb src/*.ads include/*.ads adaid.gpr @@ -93,6 +93,11 @@ $(DIST): cleanall --xform 's!$(THIS)!$(DIST_NAME)!'\ $(THIS) +#documentation +docs: include/*.ads + ls include/*.ads | adabrowse -i -o ./ -f- + @mv *.html doc + #misc all: $(LIB) $(TEST) @@ -100,5 +105,5 @@ clean: $(RM) -f obj/*.* obj/test/*.* obj/debug/*.* ali/*.* ali/debug/*.* 2> /dev/null cleanall: clean - $(RM) -f support/*.gpr bin/* lib/* adaid.gpr 2> /dev/null + $(RM) -f support/*.gpr bin/* lib/* adaid.gpr doc/*.html 2> /dev/null diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 0000000..e69de29 diff --git a/doc/adaid-generate.html b/doc/adaid-generate.html new file mode 100644 index 0000000..3c4cc0a --- /dev/null +++ b/doc/adaid-generate.html @@ -0,0 +1,124 @@ + + + + + +Package: AdaID.Generate + + + + + + + + + +

Package: AdaID.Generate

+ + +

Description

+
+ AdaID.Generate defines the functions required to generate UUIDs using + different standard methods. +
+
+ + + + + + +
+

Header

+
+
package AdaID.Generate is
+
+
+ + + + + + + +
+

Exceptions

+ + + +
+Invalid_String
+
+ Thrown when invalid strings are passed to From_String +
+
+
+
+

Other Items:

+
+ + + +
+
procedure Nil(id : in out UUID);
+
+
+ Set a UUID to Nil +
+
+
+
+ + + +
+
procedure Random(id : in out UUID);
+
+
+ Generate a random UUID +
+
+
+
+ + + +
+
procedure From_Name(namespace: in UUID; name: in String; id: in out UUID);
+
+
+ Generate a UUID based on a name +
+
+
+
+ + + +
+
procedure From_String(str : in String; id : in out UUID);
+
+
+ Generate a UUID from a string. + This is not so much generation, but reconstruction +
+
+
+
+
end AdaID.Generate;
+
+
Generated on 2012-01-20 at 11:19:19 by AdaBrowse 4.0.3.
+ + diff --git a/doc/adaid.html b/doc/adaid.html new file mode 100644 index 0000000..1319f09 --- /dev/null +++ b/doc/adaid.html @@ -0,0 +1,288 @@ + + + + + +Package: AdaID + + + + + + + + + +

Package: AdaID

+ + +

Dependencies

+
with Ada.Finalization;
+with Interfaces; use Interfaces;
+
+ for Unsigned_n +
+
+

Description

+
+ File: adaid.ads + Description: A UUID type for Ada + Author: Anthony Arnold + License: http://www.gnu.org/licenses/gpl.txt +
+
+ + + + + + +
+

Header

+
+
package AdaID is
+
+
+ + + + + + + + + + + + + + + + + + +
+

Type Summary

+ + + + + + + + +
+Byte
+ByteArray
+UUID derived from Controlled
New Operations:  +"=", +Get_Hash_Value, +Get_Variant, +Get_Version, +Is_Nil, +To_String +
Inherited Operations:  +Adjust, +Finalize, +Initialize +
+VariantType
+VersionType
+
+
+

Constants and Named Numbers

+ + + +
+uuid_size: constant Integer := 16; +
+
+ This many bytes in a UUID +
+
+
+
+

Other Items:

+
+ + + +
+
subtype HashType is Unsigned_32;
+
+
+ Represents a "Hash Code" of a UUID +
+
+
+
+ + + +
+
type Byte is mod 2 ** 8;
+
+
+ Byte Type (2^8) +
+
+
+
+ + + +
+
type ByteArray is array (0 .. uuid_size-1) of Byte;
+
+
+ Byte Array for UUID data storage +
+
+
+
+ + + +
+
type VersionType is (
+	Unknown,
+	Time_Based,
+	DCE_Security,
+	Name_Based_MD5,
+	Random_Number_Based,
+	Name_Based_SHA1
+);
+
+
+ The Version of the UUID +
+
+
+
+ + + +
+
type VariantType is (
+	NCS,
+	RFC_4122,
+	Microsoft,
+	Future
+);
+
+
+ The UUID Variant +
+
+
+
+ + + +
+
type UUID is new Ada.Finalization.Controlled with 
+record
+	data: ByteArray;
+end record;
+
+
+ The main type for the package +
+
+
+
+ + + +
+
function Is_Nil(This: in UUID) return Boolean;
+
+
+Determine if UUID is NIL (All Zeros) +
+
+
+
+ + + +
+
function Get_Version(This: in UUID) return VersionType;
+
+
+Get the UUID Version +
+
+
+
+ + + +
+
function Get_Variant(This: in UUID) return VariantType;
+
+
+Get the UUID Variant +
+
+
+
+ + + +
+
function "="(Left, Right: in UUID) return Boolean;
+
+
+Test for equality between Left and Right +
+
+
+
+ + + +
+
function Get_Hash_Value(This: in UUID) return HashType;
+
+
+Get the hash code for the UUID +
+
+
+
+ + + +
+
function To_String(This: in UUID) return String;
+
+
+Convert the UUID to a common string representation +
+
+
+
private
+
+   --  Implementation-defined ...
+
+
+
+
end AdaID;
+
+
Generated on 2012-01-20 at 11:19:19 by AdaBrowse 4.0.3.
+ + diff --git a/doc/index.html b/doc/index.html new file mode 100644 index 0000000..bcc2ae7 --- /dev/null +++ b/doc/index.html @@ -0,0 +1,39 @@ + + + + + +Unit Index + + + + + + + + + +

Unit Index

+ + +

+

A

+

+AdaID
+AdaID.Generate
+

+
Generated on 2012-01-20 at 11:19:19 by AdaBrowse 4.0.3.
+ + diff --git a/include/adaid-generate.ads b/include/adaid-generate.ads index 2438a26..cc742da 100644 --- a/include/adaid-generate.ads +++ b/include/adaid-generate.ads @@ -1,25 +1,31 @@ +------------------------------------------------------------------------------- -- File: adaid-generate.ads -- Description: UUID Generation -- Author: Anthony Arnold -- License: http://www.gnu.org/licenses/gpl.txt +------------------------------------------------------------------------------- +-- AdaID.Generate defines the functions required to generate UUIDs using +-- different standard methods. package AdaID.Generate is - - -- Exception for string parsing + Invalid_String : exception; + -- Thrown when invalid strings are passed to From_String + - -- Set a UUID to Nil procedure Nil(id : in out UUID); + -- Set a UUID to Nil + - -- Generate a random UUID procedure Random(id : in out UUID); + -- Generate a random UUID - -- Generate a UUID based on a name procedure From_Name(namespace: in UUID; name: in String; id: in out UUID); + -- Generate a UUID based on a name + procedure From_String(str : in String; id : in out UUID); -- Generate a UUID from a string. -- This is not so much generation, but reconstruction - procedure From_String(str : in String; id : in out UUID); end AdaID.Generate; diff --git a/include/adaid.ads b/include/adaid.ads index 4d31ac5..2667a0e 100644 --- a/include/adaid.ads +++ b/include/adaid.ads @@ -1,26 +1,29 @@ +------------------------------------------------------------------------------- -- File: adaid.ads -- Description: A UUID type for Ada -- Author: Anthony Arnold -- License: http://www.gnu.org/licenses/gpl.txt +------------------------------------------------------------------------------- with Ada.Finalization; with Interfaces; use Interfaces; -- for Unsigned_n + +-- AdaID defines the types and accessor/miscellaneous functions for +-- the UUID type. package AdaID is - -- Size type is unsigned - subtype SizeType is Unsigned_32; - uuid_size: constant Integer := 16; -- This many bytes in a UUID + uuid_size: constant Integer := 16; + -- This many bytes in a UUID - --Hash Type - subtype HashType is SizeType; -- The 'hash' of a UUID + subtype HashType is Unsigned_32; + -- Represents a "Hash Code" of a UUID + type Byte is mod 2 ** 8; -- Byte Type (2^8) - type Byte is mod 2 ** 8; -- 8-bit bytes - -- Byte Array for UUID data storage type ByteArray is array (0 .. uuid_size-1) of Byte; + -- Byte Array for UUID data storage - -- Some UUID Enums type VersionType is ( Unknown, Time_Based, @@ -29,6 +32,7 @@ package AdaID is Random_Number_Based, Name_Based_SHA1 ); + -- The Version of the UUID type VariantType is ( NCS, @@ -36,33 +40,34 @@ package AdaID is Microsoft, Future ); - + -- The UUID Variant + - -- The main type for the package type UUID is new Ada.Finalization.Controlled with record data: ByteArray; end record; + -- The main type for the package - --Determine if UUID is NIL function Is_Nil(This: in UUID) return Boolean; + --Determine if UUID is NIL (All Zeros) - --Get the UUID Version function Get_Version(This: in UUID) return VersionType; + --Get the UUID Version - --Get the UUID Variant function Get_Variant(This: in UUID) return VariantType; + --Get the UUID Variant - --Test for equality function "="(Left, Right: in UUID) return Boolean; + --Test for equality between Left and Right - --Get the hash value for the UUID function Get_Hash_Value(This: in UUID) return HashType; + --Get the hash code for the UUID - --Convert the UUID to a string function To_String(This: in UUID) return String; + --Convert the UUID to a common string representation private - --Default "constructor", initializes to NIL overriding procedure Initialize (This: in out UUID); + --Default "constructor", initializes to NIL end AdaID; diff --git a/lib/.gitignore b/lib/.gitignore index 10301e2..4c55d73 100644 --- a/lib/.gitignore +++ b/lib/.gitignore @@ -1 +1,2 @@ *.a +*.so*