update

src/Span.h

@@ -40,7 +40,7 @@
 
 namespace Service {
 
-  CREATE_SERV(AccessoryInformation,3E)
+  CREATE_SERV(AccessoryInformation,3E)        // Required Identification Information.  For each Accessory in a HomeSpan device this <i>must be included as the first Service.</i>
     REQ(Identify);
     OPT(FirmwareRevision);
     OPT(Manufacturer);
@@ -51,11 +51,6 @@ namespace Service {
     OPT(AccessoryFlags);
   END_SERV
 
-//! Here is some important text you need to read.
-//! Spacing is not critical since this will be
-//! formated in HTML where spaces    are       ignored.
-//! You can use *standard* markdown elements as well.
-
   CREATE_SERV(AirPurifier,BB)
     REQ(Active);
     REQ(CurrentAirPurifierState);

tools/makeServiceList

@@ -2,77 +2,60 @@
 
 BEGIN {
 
-	servicesFile = "../src/Span.h"
+	ws="[ \t,();]+"									# regexp of separators
-	charsFile = "../src/Characteristics.h"
+	ltws="^" ws "|" ws "$"					# regexp of leading and trailing separators
 
-	ws="[ \t,();]+"										# regexp of separators
+	nServs=0												# number of Services found
-	ltws="^" ws "|" ws "$"						# regexp of leading and trailing separators
+}
 
-	nServs=0
+{
+	split($0,line,"//")							# separate line into program and (optional) comment
+	gsub(ltws,"",line[1])						# strip out leading or trailing separators
 
-	while(getline < servicesFile ){
+	n=split(line[1],x,ws)						# split program portion according to separators
-
-		split($0,line,"//")
-
-		gsub(ltws,"",line[1])						# strip out leading or trailing separators
-
-		if(index($0,"//!")==1){
-			desc[currentService]=desc[currentService] " " substr($0,4)
-			continue
-		}
-
-		n=split(line[1],x,ws)
-
-		if(x[1]=="CREATE_SERV"){
-			currentService=x[2]
-			services[nServs++]=currentService
-			uuid[currentService]=x[3]
-			nChars[currentService]=0
-		}
-
-  	else if(x[1]=="REQ" || x[1]=="OPT"){
-			servChars[currentService,nChars[currentService]]=x[2]
-			servReq[currentService,nChars[currentService]]=(x[1]=="REQ")
-			nChars[currentService]++
-		}
-
-		else if(x[1]=="CREATE_CHAR"){
-			char=x[3]
-			default[char]=x[4]
-			min[char]=x[5]
-			max[char]=x[6]
-			nVals[char]=n-6							# number of pre-defined constants
-			for(i=0;i<nVals[char];i++)
-				vals[char,i]=x[i+7]
-			notes[char]=line[2]
-		}
 
+	if(x[1]=="CREATE_SERV"){
+		currentService=x[2]
+		services[nServs++]=currentService
+		uuid[currentService]=x[3]
+		desc[currentService]=line[2]	# save optional comment as description of Service
+		nChars[currentService]=0
 	}
 
-	close(servicesFile)
+ 	else if(x[1]=="REQ" || x[1]=="OPT"){
-
+		servChars[currentService,nChars[currentService]]=x[2]
-	while(getline < charsFile){
+		servReq[currentService,nChars[currentService]]=(x[1]=="REQ")
-
+		nChars[currentService]++
-		gsub(ltws,"")						# strip out leading or trailing separators
-		n=split($0,x,ws)				# split line by separators
-
-		if(x[1]=="HAPCHAR"){
-			char=x[2]
-			uuid[char]=x[3]
-			perms[char]=x[4]
-			format[char]=tolower(x[5])
-			static[char]=x[6]
-		}
-
 	}
 
-	close(charsFile)
+	else if(x[1]=="CREATE_CHAR"){
+		char=x[3]
+		default[char]=x[4]
+		min[char]=x[5]
+		max[char]=x[6]
+		nVals[char]=n-6								# parse any pre-defined constants
+		for(i=0;i<nVals[char];i++)
+			vals[char,i]=x[i+7]
+		notes[char]=line[2]						# save optional comment as notes for Characteristic
+	}
+
+	else if(x[1]=="HAPCHAR"){
+		char=x[2]
+		uuid[char]=x[3]
+		perms[char]=x[4]
+		format[char]=tolower(x[5])
+		static[char]=x[6]
+	}
+} 
+
+END {
 
 	for(i=0;i<nServs;i++){
 		s=services[i]
 		printf("## %s (%s)\n",s,uuid[s])
 		printf("<details><summary>%s</summary><br><table>\n",desc[s])
 		printf("<tr><th>Characteristic</th><th>UUID</th><th>Format</th><th>Perms</th><th>Min</th><th>Max</th><th>Constants</th><th>Notes</th></tr>\n")
+
 		for(j=0;j<nChars[s];j++){
 			char=servChars[s,j]
 			printf("<tr>")
@@ -93,9 +76,9 @@ BEGIN {
 			printf("</ul></td>")
 			printf("<td>%s</td></tr>",notes[char])
 		}
+
 		printf("</table></details>\n\n")
 	}
-		
 }
 
 

tools/test.md

@@ -1,5 +1,5 @@
 ## AccessoryInformation (3E)
-<details><summary>  Here is some important text you need to read.  Spacing is not critical since this will be  formated in HTML where spaces    are       ignored.  You can use *standard* markdown elements as well.</summary><br><table>
+<details><summary> Required Identification Information.  For each Accessory in a HomeSpan device this <i>must be included as the first Service.</i></summary><br><table>
 <tr><th>Characteristic</th><th>UUID</th><th>Format</th><th>Perms</th><th>Min</th><th>Max</th><th>Constants</th><th>Notes</th></tr>
 <tr><td><b>Identify</td><td align="center">14</td><td align="center">bool</td><td align="center">PW</td><td align="center">0</td><td align="center">1</td><td><ul></ul></td><td></td></tr><tr><td>FirmwareRevision</td><td align="center">52</td><td align="center">string</td><td align="center">PR+EV</td><td align="center">-</td><td align="center">-</td><td><ul></ul></td><td></td></tr><tr><td>Manufacturer</td><td align="center">20</td><td align="center">string</td><td align="center">PR</td><td align="center">-</td><td align="center">-</td><td><ul></ul></td><td></td></tr><tr><td>Model</td><td align="center">21</td><td align="center">string</td><td align="center">PR</td><td align="center">-</td><td align="center">-</td><td><ul></ul></td><td></td></tr><tr><td>Name</td><td align="center">23</td><td align="center">string</td><td align="center">PR</td><td align="center">-</td><td align="center">-</td><td><ul></ul></td><td></td></tr><tr><td>SerialNumber</td><td align="center">30</td><td align="center">string</td><td align="center">PR</td><td align="center">-</td><td align="center">-</td><td><ul></ul></td><td></td></tr><tr><td>HardwareRevision</td><td align="center">53</td><td align="center">string</td><td align="center">PR</td><td align="center">-</td><td align="center">-</td><td><ul></ul></td><td></td></tr><tr><td>AccessoryFlags</td><td align="center">A6</td><td align="center">uint32</td><td align="center">PR+EV</td><td align="center">1</td><td align="center">1</td><td><ul></ul></td><td> This is not really used anywhere 1/3</td></tr></table></details>