From 9456f88f00292d202ba9910b26fdb1cd0a499d93 Mon Sep 17 00:00:00 2001
From: shyouhei <shyouhei@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>
Date: Fri, 12 Jan 2018 08:38:08 +0000
Subject: [ci skip] add comments about file format (2nd try)

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@61783 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
---
 insns.def | 42 ++++++++++++++++++++++++++++++++++++++----
 1 file changed, 38 insertions(+), 4 deletions(-)

(limited to 'insns.def')

diff --git a/insns.def b/insns.def
index 7f72e9ec86..622f3b05c9 100644
--- a/insns.def
+++ b/insns.def
@@ -1,15 +1,49 @@
-/** ##skip -*- mode:c; style:ruby; coding: utf-8 -*-
+/* -*- mode:c; style:ruby; coding: utf-8 -*-
   insns.def - YARV instruction definitions
 
   $Author: $
   created at: 04/01/01 01:17:55 JST
 
   Copyright (C) 2004-2007 Koichi Sasada
+  Massive rewrite by @shyouhei in 2017.
  */
 
-/** ##skip
-  instruction comment
-  : english description
+/* Some comments about this file's contents:
+
+   - The new format aims to be editable by C editor of your choice;
+     your mileage might vary of course.
+
+   - Each instructions are in following format:
+
+     DEFINE_INSN
+     instruction_name
+     (type operand, type operand, ..)
+     (pop_values, ..)
+     (return values ..)
+     // attr type name contents..
+     {
+       .. // insn body
+     }
+
+   - Unlike the old format which was line-oriented, you can now place
+     newlines and comments at liberal positions.
+
+   - `DEFINE_INSN` is a keyword.
+
+   - An instruction name must be a valid C identifier.
+
+   - Operands, pop values, return values are series of either variable
+     declarations, keyword `void`, or keyword `...`.  They are much
+     like C function declarations.
+
+   - Attribute pragmas are optional, and can include arbitrary C
+     expressions.  You can write anything there but as of writing,
+     attribute named sp_inc is supported.
+
+   - Attributes can access operands, but not stack (push/pop) variables.
+
+   - An instruction's body is a pure C block, copied verbatimly into
+     the generated C source code.
  */
 
 /* nop */
-- 
cgit v1.2.3

