From 8965adaafbd5964e476d21af463904535c586485 Mon Sep 17 00:00:00 2001
From: Yuriy Taraday <yorik.sar@gmail.com>
Date: Fri, 2 Mar 2018 00:26:38 +0400
Subject: [PATCH] Expand some comments by Geoff's request

---
 internal/lvgen/generate.go | 11 +++++++++++
 internal/lvgen/lvlexer.go  |  4 +++-
 2 files changed, 14 insertions(+), 1 deletion(-)

diff --git a/internal/lvgen/generate.go b/internal/lvgen/generate.go
index 2b655e8..07379ab 100644
--- a/internal/lvgen/generate.go
+++ b/internal/lvgen/generate.go
@@ -564,6 +564,17 @@ func AddEnumVal(name, val string) error {
 }
 
 // AddEnumValMeta will add a new enum value with attached metadata to the list.
+// Metadata is parsed from annotations in libvirt RPC description file that are
+// in block comment preceding every function in enum, it looks like this:
+// /**
+//  * @generate: both
+//  * @readstream: 1
+//  * @sparseflag: VIR_STORAGE_VOL_DOWNLOAD_SPARSE_STREAM
+//  * @acl: storage_vol:data_read
+//  */
+// See full description of possible annotations in libvirt's src/remote/remote_protocol.x
+// at the top of remote_procedure enum.
+// We're parsing only @readstream and @writestream annotations at the moment.
 func AddEnumValMeta(name, val, meta string) error {
 	ev, err := parseNumber(val)
 	if err != nil {
diff --git a/internal/lvgen/lvlexer.go b/internal/lvgen/lvlexer.go
index be133fc..5bc7eba 100644
--- a/internal/lvgen/lvlexer.go
+++ b/internal/lvgen/lvlexer.go
@@ -259,10 +259,12 @@ func lexText(l *Lexer) stateFn {
 
 // lexBlockComment is used when we find a comment marker '/*' in the input.
 func lexBlockComment(l *Lexer) stateFn {
+	// Double star is used only at the start of metadata comments
 	metadataComment := strings.HasPrefix(l.input[l.pos:], "/**")
 	for {
 		if strings.HasPrefix(l.input[l.pos:], "*/") {
-			// Found the end. Advance past the '*/' and discard the comment body.
+			// Found the end. Advance past the '*/' and discard the comment body
+			// unless it's a metadata comment
 			l.next()
 			l.next()
 			if metadataComment {