From 1f0006ac71fd4eb308ab900b0b9917e1dd046680 Mon Sep 17 00:00:00 2001 From: Mike Pall Date: Fri, 11 Feb 2011 13:50:01 +0100 Subject: [PATCH] Cleanup of docs. --- doc/changes.html | 2 +- doc/ext_ffi.html | 79 ++++++++++++++++++-------- doc/ext_ffi_api.html | 4 +- doc/ext_ffi_semantics.html | 23 ++++---- doc/ext_ffi_tutorial.html | 111 +++++++++++++++++++++++++++---------- doc/install.html | 4 +- doc/luajit.html | 2 +- doc/status.html | 7 ++- 8 files changed, 157 insertions(+), 75 deletions(-) diff --git a/doc/changes.html b/doc/changes.html index 04e26e40..88d54cc2 100644 --- a/doc/changes.html +++ b/doc/changes.html @@ -256,7 +256,7 @@ to avoid joining by the compiler/linker.
  • Merged with Lua 5.1.1. Fixes all » known bugs in Lua 5.1.
  • Enforce (dynamic) linker error for EXE/DLL version mismatches.
    • -
  • Minor changes to DynASM: faster preprocessing, smaller encoding +
  • Minor changes to DynASM: faster pre-processing, smaller encoding for some immediates.

    • diff --git a/doc/ext_ffi.html b/doc/ext_ffi.html index 1fd276dc..0bbf7606 100644 --- a/doc/ext_ffi.html +++ b/doc/ext_ffi.html @@ -8,6 +8,12 @@ +

    @@ -55,16 +61,20 @@

    -The FFI library allows calling external C functions and the use -of C data structures from pure Lua code. + +The FFI library allows calling external C functions and +using C data structures from pure Lua code. +

    + The FFI library largely obviates the need to write tedious manual -Lua/C bindings in C. It doesn't require learning a separate binding -language — it parses plain C declarations, which can be +Lua/C bindings in C. No need to learn a separate binding language +— it parses plain C declarations! These can be cut-n-pasted from C header files or reference manuals. It's up to the task of binding large libraries without the need for dealing with fragile binding generators. +

    The FFI library is tightly integrated into LuaJIT (it's not available @@ -83,26 +93,30 @@ Please use the FFI sub-topics in the navigation bar to learn more.

    It's really easy to call an external C library function:

    -
    -local ffi = require("ffi") --①
-ffi.cdef[[ //②
+
    +①
+②
+
+
+③local ffi = require("ffi")
+ffi.cdef[[
 int printf(const char *fmt, ...);
 ]]
-ffi.C.printf("Hello %s!", "world") --③
+ffi.C.printf("Hello %s!", "world")
 
    
 
    
 So, let's pick that apart:
 
    
 
    
-① Load the FFI library.
+① Load the FFI library.
 
    
 
    
-② Add a C declaration
+② Add a C declaration
 for the function. The part inside the double-brackets (in green) is
 just standard C syntax.
 
    
 
    
-③ Call the named
+③ Call the named
 C function — Yes, it's that simple!
 
    
 
    
@@ -198,25 +212,42 @@ need of a simple example ...
 And here's the FFI version. The modified parts have been marked in
 bold:
 
    
-
    -local ffi = require("ffi") --①
-ffi.cdef[[
+
    +①
+
+
+
+
+
+②
+
+③
+④
+
+
+
+
+
+
+③
+⑤local ffi = require("ffi")
+ffi.cdef[[
 typedef struct { uint8_t red, green, blue, alpha; } rgba_pixel;
 ]]
 
 local function image_ramp_green(n)
-  local img = ffi.new("rgba_pixel[?]", n) --②
+  local img = ffi.new("rgba_pixel[?]", n)
   local f = 255/(n-1)
-  for i=0,n-1 do --③
-    img[i].green = i*f --④
+  for i=0,n-1 do
+    img[i].green = i*f
     img[i].alpha = 255
   end
   return img
 end
 
 local function image_to_grey(img, n)
-  for i=0,n-1 do --③
-    local y = 0.3*img[i].red + 0.59*img[i].green + 0.11*img[i].blue --⑤
+  for i=0,n-1 do
+    local y = 0.3*img[i].red + 0.59*img[i].green + 0.11*img[i].blue
     img[i].red = y; img[i].green = y; img[i].blue = y
   end
 end
@@ -231,30 +262,30 @@ end
 Ok, so that wasn't too difficult:
 
    
 
    
-① First, load the FFI
+① First, load the FFI
 library and declare the low-level data type. Here we choose a
 struct which holds four byte fields, one for each component
 of a 4x8 bit RGBA pixel.
 
    
 
    
-② Creating the data
+② Creating the data
 structure with ffi.new() is straightforward — the
 '?' is a placeholder for the number of elements of a
 variable-length array.
 
    
 
    
-③ C arrays are
+③ C arrays are
 zero-based, so the indexes have to run from 0 to
 n-1. One might want to allocate one more element instead to
 simplify converting legacy code.
 
    
 
    
-④ Since ffi.new()
+④ Since ffi.new()
 zero-fills the array by default, we only need to set the green and the
 alpha fields.
 
    
 
    
-⑤ The calls to
+⑤ The calls to
 math.floor() can be omitted here, because floating-point
 numbers are already truncated towards zero when converting them to an
 integer. This happens implicitly when the number is stored in the
diff --git a/doc/ext_ffi_api.html b/doc/ext_ffi_api.html
index 9bedd52e..b8c52fb6 100644
--- a/doc/ext_ffi_api.html
+++ b/doc/ext_ffi_api.html
@@ -316,7 +316,7 @@ bytes of the string plus a zero-terminator are copied to
 
    
 
    
 Performance notice: ffi.copy() may be used as a faster
-(inlineable) replacement for the C library functions
+(inlinable) replacement for the C library functions
 memcpy(), strcpy() and strncpy().
 
    
 
@@ -328,7 +328,7 @@ zero-filled.
 
    
 
    
 Performance notice: ffi.fill() may be used as a faster
-(inlineable) replacement for the C library function
+(inlinable) replacement for the C library function
 memset(dst, c, len). Please note the different
 order of arguments!
 
    
diff --git a/doc/ext_ffi_semantics.html b/doc/ext_ffi_semantics.html
index 69dfc2ca..8c7bd478 100644
--- a/doc/ext_ffi_semantics.html
+++ b/doc/ext_ffi_semantics.html
@@ -66,9 +66,9 @@ and its interaction with both Lua and C code.
 
    
 
    
 Given that the FFI library is designed to interface with C code
-and that declarations can be written in plain C syntax, it
-closely follows the C language semantics, wherever possible. Some
-minor concessions are needed for smoother interoperation with Lua
+and that declarations can be written in plain C syntax, it
+closely follows the C language semantics, wherever possible.
+Some minor concessions are needed for smoother interoperation with Lua
 language semantics.
 
    
 
    
@@ -83,9 +83,8 @@ background.
 Please note: this is the first public release of the FFI library. This
 does not comprise the final specification for the FFI semantics, yet.
 Some of the semantics may need to be changed, based on feedback from
-developers. Please report any problems
-you've encountered or any improvements you'd like to see — thank
-you!
+developers. Please report any problems you
+may encounter or any improvements you'd like to see — thank you!
 
    
 
 
    C Language Support
    
@@ -204,7 +203,7 @@ The following C features are not supported:
 default to an int type.
 
 
  • Old-style empty function declarations (K&R) are not allowed.
-All C functions must have a proper protype declaration. A
+All C functions must have a proper prototype declaration. A
 function declared without parameters (int foo();) is
 treated as a function taking zero arguments, like in C++.
    • 
 
@@ -312,7 +311,7 @@ C type of the destination, the
 are applied.
 
    
 
    
-Reference types are immutable after initialization ("no reseating of
+Reference types are immutable after initialization ("no re-seating of
 references"). For initialization purposes or when passing values to
 reference parameters, they are treated like pointers. Note that unlike
 in C++, there's no way to implement automatic reference generation of
@@ -652,8 +651,8 @@ variable argument part of vararg C function use
 special conversion rules. This
 C function is called and the return value (if any) is
 converted to a Lua object.
    
-On Windows/x86 systems, stdcall functions are automatically
-detected and a function declared as cdecl (the default) is
+On Windows/x86 systems, __stdcall functions are automatically
+detected and a function declared as __cdecl (the default) is
 silently fixed up after the first call.
 
 
@@ -790,7 +789,7 @@ local s = ffi.new("foo_t", a)
 Similar rules apply for Lua strings which are implicitly converted to
 "const char *": the string object itself must be
 referenced somewhere or it'll be garbage collected eventually. The
-pointer will then point to stale data, which may have already beeen
+pointer will then point to stale data, which may have already been
 overwritten. Note that string literals are automatically kept
 alive as long as the function containing it (actually its prototype)
 is not garbage collected.
@@ -951,7 +950,7 @@ storing and initializing them are supported, yet.
 
  • The volatile type qualifier is currently ignored by
 compiled code.
    • 
 
  • ffi.cdef silently
-ignores all redeclarations.
    • 
+ignores all re-declarations.
 
 
    
 The JIT compiler already handles a large subset of all FFI operations.
diff --git a/doc/ext_ffi_tutorial.html b/doc/ext_ffi_tutorial.html
index c43b223b..38126865 100644
--- a/doc/ext_ffi_tutorial.html
+++ b/doc/ext_ffi_tutorial.html
@@ -9,7 +9,12 @@