From af07986eecc21faffe6d9e24f634b4108129bbd1 Mon Sep 17 00:00:00 2001
From: Jocelyn Fiat <jfiat@eiffel.com>
Date: Fri, 23 Nov 2012 22:49:11 +0100
Subject: [PATCH] New design for self documented router. The documentation is
 built only on demand. A mapping entry can be hidden for the documentation One
 can change the status code when building itself the
 WSF_ROUTER_SELF_DOCUMENTATION_MESSAGE

---
 .../wsf_router_mapping_documentation.e        |  52 ++++++
 .../wsf_router_self_documentation_message.e   | 155 ++++++++++--------
 .../wsf_self_documented_handler.e             |   2 +-
 .../wsf_self_documented_router_mapping.e      |  12 +-
 .../starts_with/wsf_starts_with_mapping.e     |   2 +-
 .../wsf/router/support/uri/wsf_uri_mapping.e  |   2 +-
 .../uri_template/wsf_uri_template_mapping.e   |   2 +-
 .../wsf_uri_template_context_mapping.e        |   2 +-
 .../server/wsf/router/wsf_router_mapping.e    |   8 +
 9 files changed, 163 insertions(+), 74 deletions(-)
 create mode 100644 library/server/wsf/router/documentation/wsf_router_mapping_documentation.e

diff --git a/library/server/wsf/router/documentation/wsf_router_mapping_documentation.e b/library/server/wsf/router/documentation/wsf_router_mapping_documentation.e
new file mode 100644
index 00000000..ea334357
--- /dev/null
+++ b/library/server/wsf/router/documentation/wsf_router_mapping_documentation.e
@@ -0,0 +1,52 @@
+note
+	description: "Summary description for {WSF_ROUTER_MAPPING_DOCUMENTATION}."
+	date: "$Date$"
+	revision: "$Revision$"
+
+class
+	WSF_ROUTER_MAPPING_DOCUMENTATION
+
+create
+	make
+
+feature {NONE} -- Initialization
+
+	make (m: like mapping)
+		do
+			mapping := m
+			create {STRING_32} description.make_empty
+		end
+
+feature -- Status report
+
+	is_hidden: BOOLEAN
+			-- Hide this mapping from any self documentation?		
+			-- Default=False
+
+	is_empty: BOOLEAN
+			-- Is Current empty?
+			-- i.e: does not carry any information.
+		do
+			Result := description.is_empty
+		end
+
+feature -- Access
+
+	mapping: WSF_ROUTER_MAPPING
+			-- Associated mapping
+
+	description: STRING_32
+
+feature -- Change
+
+	set_is_hidden (b: BOOLEAN)
+		do
+			is_hidden := b
+		end
+
+	add_description (d: READABLE_STRING_GENERAL)
+		do
+			description.append_string_general (d)
+		end
+
+end
diff --git a/library/server/wsf/router/documentation/wsf_router_self_documentation_message.e b/library/server/wsf/router/documentation/wsf_router_self_documentation_message.e
index cc2e5d7f..051446a9 100644
--- a/library/server/wsf/router/documentation/wsf_router_self_documentation_message.e
+++ b/library/server/wsf/router/documentation/wsf_router_self_documentation_message.e
@@ -21,6 +21,7 @@ feature {NONE} -- Initialization
 	make (req: WSF_REQUEST; a_router: WSF_ROUTER)
 			-- Make Current for request `req' and router `a_router'
 		do
+			status_code := {HTTP_STATUS_CODE}.ok
 			request := req
 			router := a_router
 		end
@@ -31,13 +32,21 @@ feature {NONE} -- Initialization
 			--| note: it could be "/doc" or "/api/doc" or ...
 		do
 			make (req, a_router)
-			if a_resource /= Void and then attached a_router.base_url as l_base_url then
-				resource := l_base_url + a_resource
+			if a_resource /= Void then
+				if attached a_router.base_url as l_base_url then
+					resource := l_base_url + a_resource
+				else
+					resource := a_resource
+				end
 			end
 		end
 
 feature -- Access		
 
+	status_code: INTEGER
+			-- Associated status code
+			-- Default is Ok
+
 	request: WSF_REQUEST
 
 	router: WSF_ROUTER
@@ -57,6 +66,13 @@ feature -- Properties
 
 feature -- Change
 
+	set_status_code (c: like status_code)
+		require
+			c_positive_or_zero: c >= 0
+		do
+			status_code := c
+		end
+
 	set_header (v: like header)
 		do
 			header := v
@@ -97,8 +113,10 @@ feature {WSF_RESPONSE} -- Output
 				l_description.append ("[
 						<style type="text/css">
 							.mappingresource { color: #00f; }
-							.mappingdoc { color: #900; }
+							.mappingdoc { color: #900; float: right}
 							.handlerdoc { white-space: pre; }
+							ul.mapping { margin: 0; padding: 5px; list-style-type: none; }
+							ul.mapping>li { margin-bottom: 5px; padding-left: 5px; border-left: solid 3px #ccc; border-top: dotted 1px #ccc; }
 							div#footer { padding: 10px; width: 100%; margin-top: 20px;  border-top: 1px dotted #999; color: #999; text-align: center; }
 						</style>
 						]")
@@ -141,12 +159,12 @@ feature {WSF_RESPONSE} -- Output
 					l_description.append ("<a href=%""+ doc_url ("") + "%">Index</a><br/>")
 				end
 				if attached router.item_associated_with_resource (l_api_resource, Void) as l_api_item then
-					l_description.append ("<h2>Information related to %"" + l_api_resource + "%"</h2><ul>")
+					l_description.append ("<h2>Information related to <code>" + l_api_resource + "</code></h2><ul class=%"mapping%">")
 					append_documentation_to (l_description, l_api_item.mapping, l_api_item.request_methods)
 					l_description.append ("</ul>")
 				end
 			else
-				l_description.append ("<h2>Router</h2><ul>")
+				l_description.append ("<h2>Router</h2><ul class=%"mapping%">")
 				across
 					router as c
 				loop
@@ -165,9 +183,10 @@ feature {WSF_RESPONSE} -- Output
 
 			l_description.append ("</body></html>")
 
+			-- Compute and send the response message
 			h.put_content_length (l_description.count)
 			h.put_current_date
-			res.set_status_code ({HTTP_STATUS_CODE}.ok)
+			res.set_status_code (status_code)
 			res.put_header_text (h.string)
 			res.put_string (l_description)
 		end
@@ -177,76 +196,78 @@ feature {WSF_RESPONSE} -- Output
 			l_url: detachable STRING_8
 			l_base_url: detachable READABLE_STRING_8
 			hdl: WSF_HANDLER
+			l_doc: detachable WSF_ROUTER_MAPPING_DOCUMENTATION
 		do
-			l_base_url := router.base_url
-			if l_base_url = Void then
-				l_base_url := ""
-			end
-
-			l_url := Void
-			s.append ("<li>")
-			s.append ("<code>")
-			if doc_url_supported then
-				s.append ("<a class=%"mappingresource%" href=%"")
-				s.append (doc_url (m.associated_resource))
-				s.append ("%">")
-				s.append (m.associated_resource)
-				s.append ("</a>")
-			else
-				s.append (m.associated_resource)
-			end
-			s.append ("</code>")
-
 			if attached {WSF_SELF_DOCUMENTED_ROUTER_MAPPING} m as l_doc_mapping then
-				s.append (" <em class=%"mappingdoc%">" + html_encoder.encoded_string (l_doc_mapping.documentation) + "</em> ")
-			else
-				debug
-					s.append (" <em class=%"mappingdoc%">" + m.generating_type.out + "</em> ")
-				end
-			end
-			if meths /= Void then
-				s.append (" [")
-				across
-					meths as rq
-				loop
-					s.append (" ")
-					if l_url /= Void and then rq.item.is_case_insensitive_equal ("GET") then
-						s.append ("<a href=%"" + l_base_url + l_url + "%">" + rq.item + "</a>")
-					else
-						s.append (rq.item)
-					end
-					s.append (",")
-				end
-				if s[s.count] = ',' then
-					s.put (' ', s.count) -- Remove last ','
-				else
-					s.append_character (' ')
-				end
-				s.append_character (']')
+				l_doc := l_doc_mapping.documentation
 			end
+			if l_doc = Void or else not l_doc.is_hidden then
 
-			hdl := m.handler
-			if attached {WSF_SELF_DOCUMENTED_HANDLER} hdl as l_doc_handler and then attached l_doc_handler.documentation as l_doc then
-				s.append ("%N<ul class=%"handlerdoc%">")
-				s.append (html_encoder.encoded_string (l_doc))
-				s.append ("%N</ul>%N")
-			else
-				debug
+				l_base_url := router.base_url
+				if l_base_url = Void then
+					l_base_url := ""
+				end
+
+				l_url := Void
+				s.append ("<li>")
+				s.append ("<code>")
+				if doc_url_supported then
+					s.append ("<a class=%"mappingresource%" href=%"")
+					s.append (doc_url (m.associated_resource))
+					s.append ("%">")
+					s.append (m.associated_resource)
+					s.append ("</a>")
+				else
+					s.append (m.associated_resource)
+				end
+				s.append ("</code>")
+
+				if meths /= Void then
+					s.append (" [ ")
+					across
+						meths as rq
+					loop
+						if l_url /= Void and then rq.item.is_case_insensitive_equal ("GET") then
+							s.append ("<a href=%"" + l_base_url + l_url + "%">" + rq.item + "</a>")
+						else
+							s.append (rq.item)
+						end
+						if not rq.is_last then
+							s.append (",")
+						end
+						s.append (" ")
+					end
+					s.append ("]")
+				end
+
+				s.append (" <em class=%"mappingdoc%">" + html_encoder.encoded_string (m.description) + "</em> ")
+
+				if l_doc /= Void and then not l_doc.is_empty then
 					s.append ("%N<ul class=%"handlerdoc%">")
-					s.append (hdl.generating_type.out)
+					s.append (html_encoder.encoded_string (l_doc.description))
+					s.append ("%N</ul>%N")
+				else
+					debug
+						s.append ("%N<ul class=%"handlerdoc%">")
+						s.append (m.handler.generating_type.out)
+						s.append ("%N</ul>%N")
+					end
+				end
+				if attached {WSF_ROUTING_HANDLER} m.handler as l_routing_hdl then
+					s.append ("%N<ul>%N")
+					across
+						l_routing_hdl.router as c
+					loop
+						append_documentation_to (s, c.item.mapping, c.item.request_methods)
+					end
 					s.append ("%N</ul>%N")
 				end
-			end
-			if attached {WSF_ROUTING_HANDLER} hdl as l_routing_hdl then
-				s.append ("%N<ul>%N")
-				across
-					l_routing_hdl.router as c
-				loop
-					append_documentation_to (s, c.item.mapping, c.item.request_methods)
+				s.append ("</li>%N")
+			else
+				debug
+					s.append ("<li>" + m.associated_resource + " is HIDDEN</li>%N")
 				end
-				s.append ("%N</ul>%N")
 			end
-			s.append ("</li>%N")
 		end
 
 feature {NONE} -- Implementation
diff --git a/library/server/wsf/router/documentation/wsf_self_documented_handler.e b/library/server/wsf/router/documentation/wsf_self_documented_handler.e
index 666b2454..8617759c 100644
--- a/library/server/wsf/router/documentation/wsf_self_documented_handler.e
+++ b/library/server/wsf/router/documentation/wsf_self_documented_handler.e
@@ -9,7 +9,7 @@ deferred class
 
 feature -- Documentation
 
-	documentation: detachable READABLE_STRING_32
+	mapping_documentation (m: WSF_ROUTER_MAPPING): WSF_ROUTER_MAPPING_DOCUMENTATION
 		deferred
 		end
 
diff --git a/library/server/wsf/router/documentation/wsf_self_documented_router_mapping.e b/library/server/wsf/router/documentation/wsf_self_documented_router_mapping.e
index daafb07d..e4281de9 100644
--- a/library/server/wsf/router/documentation/wsf_self_documented_router_mapping.e
+++ b/library/server/wsf/router/documentation/wsf_self_documented_router_mapping.e
@@ -7,10 +7,18 @@ note
 deferred class
 	WSF_SELF_DOCUMENTED_ROUTER_MAPPING
 
+inherit
+	WSF_ROUTER_MAPPING
+
 feature -- Documentation
 
-	documentation: READABLE_STRING_32
-		deferred
+	documentation: WSF_ROUTER_MAPPING_DOCUMENTATION
+		do
+			if attached {WSF_SELF_DOCUMENTED_HANDLER} handler as obj then
+				Result := obj.mapping_documentation (Current)
+			else
+				create Result.make (Current)
+			end
 		end
 
 end
diff --git a/library/server/wsf/router/support/starts_with/wsf_starts_with_mapping.e b/library/server/wsf/router/support/starts_with/wsf_starts_with_mapping.e
index 35eec54b..e62ffb50 100644
--- a/library/server/wsf/router/support/starts_with/wsf_starts_with_mapping.e
+++ b/library/server/wsf/router/support/starts_with/wsf_starts_with_mapping.e
@@ -35,7 +35,7 @@ feature -- Access
 
 feature -- Documentation
 
-	documentation: STRING_32 = "Starts-With-URI"
+	description: STRING_32 = "Starts-With-URI"
 
 feature -- Status
 
diff --git a/library/server/wsf/router/support/uri/wsf_uri_mapping.e b/library/server/wsf/router/support/uri/wsf_uri_mapping.e
index 4bd74ce1..ce271b9e 100644
--- a/library/server/wsf/router/support/uri/wsf_uri_mapping.e
+++ b/library/server/wsf/router/support/uri/wsf_uri_mapping.e
@@ -46,7 +46,7 @@ feature -- Access
 
 feature -- Documentation
 
-	documentation: STRING_32 = "Is-URI"
+	description: STRING_32 = "Is-URI"
 
 feature -- Status
 
diff --git a/library/server/wsf/router/support/uri_template/wsf_uri_template_mapping.e b/library/server/wsf/router/support/uri_template/wsf_uri_template_mapping.e
index a8cee792..94dc3683 100644
--- a/library/server/wsf/router/support/uri_template/wsf_uri_template_mapping.e
+++ b/library/server/wsf/router/support/uri_template/wsf_uri_template_mapping.e
@@ -45,7 +45,7 @@ feature -- Access
 
 feature -- Documentation
 
-	documentation: STRING_32 = "Match-URI-Template"
+	description: STRING_32 = "Match-URI-Template"
 
 feature -- Status report
 
diff --git a/library/server/wsf/router/support/uri_template_with_context/wsf_uri_template_context_mapping.e b/library/server/wsf/router/support/uri_template_with_context/wsf_uri_template_context_mapping.e
index 9f76d416..4f9d00ab 100644
--- a/library/server/wsf/router/support/uri_template_with_context/wsf_uri_template_context_mapping.e
+++ b/library/server/wsf/router/support/uri_template_with_context/wsf_uri_template_context_mapping.e
@@ -45,7 +45,7 @@ feature -- Access
 
 feature -- Documentation
 
-	documentation: STRING_32 = "Is-URI"
+	description: STRING_32 = "Is-URI"
 
 feature -- Status report
 
diff --git a/library/server/wsf/router/wsf_router_mapping.e b/library/server/wsf/router/wsf_router_mapping.e
index b8c8243b..fcae82a0 100644
--- a/library/server/wsf/router/wsf_router_mapping.e
+++ b/library/server/wsf/router/wsf_router_mapping.e
@@ -10,6 +10,7 @@ deferred class
 feature {NONE} -- Initialization
 
 	make (a_resource: READABLE_STRING_8; h: like handler)
+			-- Create mapping based on resource `a_resource' and handler `h'
 		deferred
 		end
 
@@ -25,6 +26,13 @@ feature -- Access
 		deferred
 		end
 
+feature -- Documentation
+
+	description: READABLE_STRING_32
+			-- Short description of associated mapping.
+		deferred
+		end
+
 feature -- Status
 
 	routed_handler (req: WSF_REQUEST; res: WSF_RESPONSE; a_router: WSF_ROUTER): detachable WSF_HANDLER