(use eggdoc)

(define doc
  `((eggdoc:begin
     (name "binary-heap")
     (description "Binary heap.")
     (author (url "http://chicken.wiki.br/users/ivan-raikov" "Ivan Raikov"))

     (history 
      (version "1.0" "Initial release"))

     (requires (url "datatype.html" "datatype")
	       (url "matchable.html" "matchable"))

     (usage "(require-extension binary-heap)")

     (download "binary-heap.egg")

     (documentation
      
      (p "The " (tt "binary-heap") " library is based on the Ocaml "
	 "heap implementation by Jean-Christophe Filliatre. ")

      (p "Heaps are encoded as binary trees that have the heap property, "
	 "namely the value of any node is greater or equal than the nodes in "
	 "its left and right subtrees. ")

      (p "A binary-heap object is created by procedure " (tt "make-binary-heap") 
	 ", the only user-visible procedure defined in this egg: "
	 
	 (procedure "make-binary-heap:: KEY-COMPARE-PROC -> SELECTOR"
		    (p "where KEY-COMPARE-PROC is a user-supplied function "
		       "that takes two keys and returns a "
		       "negative, positive, or zero number "
		       "depending on how the first key compares to "
		       "the second. ")
		    (p "The returned selector procedure can take one of the following arguments: "
		       (symbol-table 

			(describe "'get-max"
				  ("returns a (key . value) pair for an association in the "
				   "heap with the largest key. If the heap is empty, an error "
				   "is signalled."))
			
			(describe "'delete-max"
				  ("removes the max key and the corresponding association "
				   "from the heap. Returns a (key . value) pair of the "
				   "removed association. If the heap is empty, an error is signalled.")) 
			
			(describe "'empty?"
				  ("returns " (tt "#t") " if the heap is empty"))
			
			(describe "'size"
				  ("returns the size (the number of associations) in the heap"))
			
			(describe "'put"
				  ("pure variant of " (tt "PUT!") "; it returns a new heap "
				   "object that contains the given association, while the original "
				   "heap object is unmodified. "))
			
			
			(describe "'for-each"
				  ("returns a procedure " (tt "LAMBDA PROC") 
				   " that will apply the given procedure PROC to each (key . value) "
				   "association of the heap, from the one with the smallest key "
				   "all the way to the one with the max key, in an ascending order "
				   "of keys. "))
			
			(describe "'fold"
				  ("returns a procedure " (tt "LAMBDA PROC INITIAL") " such that, "
				   "given the associations in the heap ordered by the descending order of keys: "
				   (tt "(key-n . value-n) ... (key-2 . value-2) (key-1 . value-1) ") " "
				   "the procedure returns the result of the successive function applications "
				   (tt "(PROC value-1 (PROC value-2 ... (PROC value-n INITIAL)") ". "))
			
			)))))

     (examples (pre #<<EOF

EOF
))
     (license
      "Copyright 2007-2009 Ivan Raikov.

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or (at
your option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

A full copy of the GPL license can be found at
<http://www.gnu.org/licenses/>."))))

(if (eggdoc->html doc) (void))