From 6586e72e8f3acf623158699abd6cf75e428d83b8 Mon Sep 17 00:00:00 2001
From: Alexander Gavrilov <angavrilov@gmail.com>
Date: Mon, 9 Jan 2012 11:48:32 +0400
Subject: [PATCH] Emit more comments into the generated headers.

---
 Bitfield.pm     |  6 +++++-
 Common.pm       | 43 +++++++++++++++++++++++++++++++++++++++++++
 Enum.pm         |  5 ++++-
 StructFields.pm | 15 +++++----------
 StructType.pm   |  6 ++++--
 5 files changed, 61 insertions(+), 14 deletions(-)

diff --git a/Bitfield.pm b/Bitfield.pm
index 74c9d2c85..3762979aa 100644
--- a/Bitfield.pm
+++ b/Bitfield.pm
@@ -28,6 +28,8 @@ sub render_bitfield_core {
     my $mod = ($tag->nodeName eq 'ld:global-type' ? "$export_prefix extern" : 'static');
     emit "$mod const bitfield_item_info ${name}_items_[sizeof($base)*8];";
 
+    emit_comment $tag, -attr => 1;
+
     emit_block {
         emit $base, ' whole;';
 
@@ -40,7 +42,9 @@ sub render_bitfield_core {
                 check_bad_attrs($item);
                 my $name = ensure_name $item->getAttribute('name');
                 my $size = $item->getAttribute('count') || 1;
-                emit "unsigned ", $name, " : ", $size, ";";
+
+                emit_comment $item;
+                emit "unsigned ", $name, " : ", $size, ";", get_comment($item);
             }
         } "struct ", " bits;";
 
diff --git a/Common.pm b/Common.pm
index d1eba18f4..88fd1389f 100644
--- a/Common.pm
+++ b/Common.pm
@@ -26,6 +26,7 @@ BEGIN {
         &ensure_name &with_anon
 
         &fully_qualified_name
+        &get_comment &emit_comment
     );
     our %EXPORT_TAGS = ( ); # eg: TAG => [ qw!name1 name2! ],
     our @EXPORT_OK   = qw( );
@@ -277,4 +278,46 @@ sub fully_qualified_name($$;$) {
     return join('::',@names,$name);
 }
 
+# Comments
+
+sub get_comment($) {
+    my ($tag) = @_;
+
+    return '' unless $tag;
+
+    if (my $val = $tag->getAttribute('comment')) {
+        return ' /*!< '.$val.' */';
+    } else {
+        return '';
+    }
+}
+
+sub emit_comment($;%) {
+    my ($tag,%flags) = @_;
+
+    return unless $tag;
+
+    my $val = $tag->findvalue('child::comment');
+
+    if ($flags{-attr}) {
+        my $attr = $tag->getAttribute('comment');
+        if ($attr && $val) {
+            $val = $attr."\n".$val;
+        } else {
+            $val ||= $attr;
+        }
+    }
+
+    if ($val) {
+        emit '/**';
+        for my $line (split(/\n/, $val)) {
+            $line =~ s/^\s*//;
+            $line =~ s/\s*$//;
+            next if $line eq '';
+            emit ' * ', $line;
+        }
+        emit ' */';
+    }
+}
+
 1;
diff --git a/Enum.pm b/Enum.pm
index 06f8ebf72..f7842858d 100644
--- a/Enum.pm
+++ b/Enum.pm
@@ -24,6 +24,8 @@ sub render_enum_core($$) {
 
     my $base = 0;
 
+    emit_comment $tag, -attr => 1;
+
     emit_block {
         my @items = $tag->findnodes('child::enum-item');
         my $idx = 0;
@@ -35,7 +37,8 @@ sub render_enum_core($$) {
             $base = ($idx == 0) ? $value : undef if defined $value;
             $idx++;
 
-            emit $name, (defined($value) ? ' = '.$value : ''), ',';
+            emit_comment $item;
+            emit $name, (defined($value) ? ' = '.$value : ''), ',', get_comment($item);
         }
 
         emit "_last_item_of_$name";
diff --git a/StructFields.pm b/StructFields.pm
index 0c515d7b3..8a188ae44 100644
--- a/StructFields.pm
+++ b/StructFields.pm
@@ -36,7 +36,9 @@ sub with_struct_block(&$;$%) {
     my $kwd = (is_attr_true($tag,'is-union') ? "union" : "struct");
     my $exp = $flags{-export} ? $export_prefix : '';
     my $prefix = $kwd.' '.$exp.($name ? $name.' ' : '');
-    
+
+    emit_comment $tag, -attr => 1;
+
     emit_block {
         local $_;
         local $in_struct_body = 1;
@@ -208,19 +210,12 @@ sub render_struct_field($) {
 
     # Otherwise, create the name if necessary, and render
     my $field_name = $tag->getAttribute('name');
-    my $field_comment = $tag->getAttribute('comment');
     my $name = ensure_name $field_name;
     $tag->setAttribute('ld:anon-name', $name) unless $field_name;
     with_anon {
         my ($prefix, $postfix) = get_struct_field_type($tag, -local => 1);
-        if($field_comment)
-        {
-            emit $prefix, ' ', $name, $postfix, ';', ' /*!< ', $field_comment, ' */';
-        }
-        else
-        {
-            emit $prefix, ' ', $name, $postfix, ';';
-        }
+        emit_comment $tag;
+        emit $prefix, ' ', $name, $postfix, ';', get_comment($tag);
     } "T_$name";
 }
 
diff --git a/StructType.pm b/StructType.pm
index f997140b7..661728c52 100644
--- a/StructType.pm
+++ b/StructType.pm
@@ -164,11 +164,13 @@ sub render_virtual_methods {
 
             my $ret_stmt = '';
             unless ($ret_type eq 'void') {
-                $ret_stmt = ' return '.($ret_type =~ /\*$/ ? '0' : "$ret_type()").'; ';
+                $ret_stmt = ' return '.($ret_type =~ /\*$/ ? '0' : "$ret_type()").';';
             }
 
+            emit_comment $method;
             emit 'virtual ', ($is_destructor?'~':$ret_type.' '), $name,
-                 '(', join(', ', @arg_strs), ') {', $ret_stmt, '}; //', $idx;
+                 '(', join(', ', @arg_strs), ') {', $ret_stmt, ' /*', $idx, '*/ };',
+                 get_comment($method);
         } "anon_vmethod_$idx";
     }
 }