wslua: Convert more comment markup to Asciidoctor.

Convert links, source code blocks, and admonitions.

Change-Id: I50c8daa19a115c23f7501b91dbfd904779a609c9
Reviewed-on: https://code.wireshark.org/review/25720
Petri-Dish: Gerald Combs <gerald@wireshark.org>
Tested-by: Petri Dish Buildbot
Reviewed-by: Gerald Combs <gerald@wireshark.org>
This commit is contained in:
Gerald Combs 2018-02-09 12:56:58 -08:00
parent 04df34909f
commit 5a674d05c9
18 changed files with 108 additions and 95 deletions

View File

@ -57,20 +57,9 @@ sub gorolla {
$s =~ s/^([\n]|\s)*//ms;
# remove trailing newlines and spaces at end
$s =~ s/([\n]|\s)*$//s;
# escape HTML entities everywhere
# bold and italics - but don't change a star followed by space (it's a list item)
$s =~ s/(\*\*)([^*]+?)(\*\*)/`$2`/g; # bold=command??
# one backtick is quote/command
#$s =~ s/([^`]|^)(`)([^`]+?)(`)/$1<command>$3<\/command>/g; # quote=command??
# two backticks are one (...and don't appear anywhere?)
#$s =~ s/(``)([^`]+?)(``)/`$2`/g; # quote=command??
# Convert wiki-style '[[url]]'
$s =~ s/(\[\[)([^\]\|]+?)(\]\])/link:\$\$$2\$\$:[$2]/g;
# handle '[[url|pretty]]'
$s =~ s/(\[\[)(([^\]\|]+?)\|\s*([^\]]+?))(\]\])/link:\$\$$3\$\$:[$4]/g;
# Prior versions converted a custom markup syntax to DocBook.
# Markup must now be compatible with Asciidoctor.
$s;
}
@ -103,17 +92,22 @@ sub parse_desc_common {
# save number of spaces in case we need to know later
my $indent = length($1);
# if we find @code then treat it as a blob
if ($lines[$idx] =~ /^\@code\b/) {
my $line = $lines[$idx];
$line =~ s/\@code/[source,lua]\n----\n/;
# if this line didn't have ending token, keep eating paragraphs
while (!($line =~ /\@endcode\b/) && $idx <= $#lines) {
# also insert back the line separator we ate in earlier split()
$line .= $lines[++$idx] . "\n";
# if we find [source,...] then treat it as a blob
if ($lines[$idx] =~ /^\[source.*\]/) {
my $line = $lines[$idx] . "\n";
# the next line *should* be a delimiter...
my $block_delim = $lines[++$idx];
$block_delim =~ s/^\s+|\s+$//g;
$line .= $block_delim . "\n";
my $block_line = $lines[++$idx];
while (!($block_line =~ qr/^\s*$block_delim\s*$/) && $idx <= $#lines) {
# keep eating lines until the closing delimiter.
# XXX Strip $indent spaces?
$line .= $block_line . "\n";
$block_line = $lines[++$idx];
}
# fix ending token, and also remove trailing whitespace before it
$line =~ s/[\s\n]*\@endcode/\n----/;
$line .= $block_delim . "\n";
$r[++$#r] = $line . "\n";
} elsif ($lines[$idx] =~ /^\s*$/) {
# line is either empty or just whitespace, and we're not in a @code block
@ -124,34 +118,8 @@ sub parse_desc_common {
# Add it as-is.
my $line = $lines[$idx];
# If line starts with "Note:" or "@note", make it an admonition
if ($line =~ /^[nN]ote:|^\@note /) {
$r[++$#r] = "[NOTE]\n";
$r[++$#r] = "====\n";
$line =~ s/^([nN]ote:\s*|\@note\s*)//;
$r[++$#r] = "" . $line . "\n";
# keep eating until we find a blank line or end
while (!($lines[++$idx] =~ /^\s*$/) && $idx <= $#lines) {
$lines[$idx] =~ s/^(\s*)//; # remove leading whitespace
$r[++$#r] = "" . $lines[$idx]. "\n";
}
$r[++$#r] = "====\n\n";
# If line starts with "Warning:"" or @warning", make it an admonition
} elsif ($line =~ /^[wW]arning:|^\@warning /) {
$r[++$#r] = "[WARNING]\n";
$r[++$#r] = "====\n";
$line =~ s/^(wW]arning:\s*|\@warning\s*)//;
# keep eating until we find a blank line or end
$r[++$#r] = "" . $line . "\n";
while (!($lines[++$idx] =~ /^\s*$/) && $idx <= $#lines) {
$lines[$idx] =~ s/^(\s*)//; # remove leading whitespace
$r[++$#r] = "" . $lines[$idx] . "\n";
}
$r[++$#r] = "====\n";
# if line starts with "@version" or "@since", make it a "Since:"
} elsif ($line =~ /^\@version |^\@since /) {
if ($line =~ /^\@version |^\@since /) {
$line =~ s/^\@version\s+|^\@since\s+/Since: /;
$r[++$#r] = "\n" . $line . "\n\n";

View File

@ -566,7 +566,7 @@ extern int wslua_reg_attributes(lua_State *L, const wslua_attribute_table *t, gb
})
/* to make this integral-safe, we treat it as int32 and then cast
Note: this will truncate 64-bit integers (but then Lua itself only has doubles */
Note: This will truncate 64-bit integers (but then Lua itself only has doubles */
#define WSLUA_ATTRIBUTE_NAMED_NUMBER_SETTER(C,name,member,cast) \
WSLUA_ATTRIBUTE_SET(C,name, { \
if (! lua_isnumber(L,-1) ) \

View File

@ -132,7 +132,11 @@ WSLUA_ATTRIBUTE_NAMED_OPT_BLOCK_STRING_SETTER(CaptureInfo,user_app,wth->shb_hdrs
For example, if the capture file identifies one resolved IPv4 address of 1.2.3.4 to `foo.com`, then you must set
`CaptureInfo.hosts` to a table of:
@code { ipv4_addresses = { { addr = "\01\02\03\04", name = "foo.com" } } } @endcode
[source,lua]
----
{ ipv4_addresses = { { addr = "\01\02\03\04", name = "foo.com" } } }
----
Note that either the `ipv4_addresses` or the `ipv6_addresses` table, or both, may be empty or nil.
*/
@ -376,7 +380,11 @@ WSLUA_ATTRIBUTE_NAMED_OPT_BLOCK_STRING_GETTER(CaptureInfoConst,user_app,wth->shb
For example, if the current capture has one resolved IPv4 address of 1.2.3.4 to `foo.com`, then getting
`CaptureInfoConst.hosts` will get a table of:
@code { ipv4_addresses = { { addr = "\01\02\03\04", name = "foo.com" } }, ipv6_addresses = { } } @endcode
[source,lua]
----
{ ipv4_addresses = { { addr = "\01\02\03\04", name = "foo.com" } }, ipv6_addresses = { } }
----
Note that either the `ipv4_addresses` or the `ipv6_addresses` table, or both, may be empty, however they will not
be nil. */

View File

@ -173,7 +173,10 @@ WSLUA_CONSTRUCTOR Dir_remove_all(lua_State* L) {
WSLUA_CONSTRUCTOR Dir_open(lua_State* L) {
/* Opens a directory and returns a `Dir` object representing the files in the directory.
@code for filename in Dir.open(path) do ... end @endcode
[source,lua]
----
for filename in Dir.open(path) do ... end
----
*/
#define WSLUA_ARG_Dir_open_PATHNAME 1 /* The pathname of the directory. */
#define WSLUA_OPTARG_Dir_open_EXTENSION 2 /* If given, only files with this extension will be returned. */

View File

@ -56,7 +56,7 @@ compare_dissector_key_name(gconstpointer dissector_a, gconstpointer dissector_b)
WSLUA_CONSTRUCTOR Dissector_list (lua_State *L) {
/* Gets a Lua array table of all registered Dissector names.
Note: this is an expensive operation, and should only be used for troubleshooting.
Note: This is an expensive operation, and should only be used for troubleshooting.
@since 1.11.3
*/
@ -231,7 +231,7 @@ WSLUA_CONSTRUCTOR DissectorTable_list (lua_State *L) {
/* Gets a Lua array table of all DissectorTable names - i.e., the string names you can
use for the first argument to DissectorTable.get().
Note: this is an expensive operation, and should only be used for troubleshooting.
Note: This is an expensive operation, and should only be used for troubleshooting.
@since 1.11.3
*/
@ -259,7 +259,7 @@ WSLUA_CONSTRUCTOR DissectorTable_heuristic_list (lua_State *L) {
/* Gets a Lua array table of all heuristic list names - i.e., the string names you can
use for the first argument in Proto:register_heuristic().
Note: this is an expensive operation, and should only be used for troubleshooting.
Note: This is an expensive operation, and should only be used for troubleshooting.
@since 1.11.3
*/

View File

@ -625,7 +625,7 @@ WSLUA_CONSTRUCTOR Field_new(lua_State *L) {
WSLUA_CONSTRUCTOR Field_list(lua_State *L) {
/* Gets a Lua array table of all registered field filter names.
NOTE: this is an expensive operation, and should only be used for troubleshooting.
NOTE: This is an expensive operation, and should only be used for troubleshooting.
@since 1.11.3
*/

View File

@ -55,11 +55,13 @@ WSLUA_CLASS_DEFINE(File,FAIL_ON_NULL_OR_EXPIRED("File"));
`write_open()`, `write()`, and `write_close()`, then the File object's `read()` and `lines()`
functions are not usable and will raise an error if used.
Note: a `File` object should never be stored/saved beyond the scope of the callback function
Note: A `File` object should never be stored/saved beyond the scope of the callback function
it is passed in to.
For example:
@code
[source,lua]
----
function myfilehandler.read_open(file, capture)
local position = file:seek()
@ -74,7 +76,7 @@ WSLUA_CLASS_DEFINE(File,FAIL_ON_NULL_OR_EXPIRED("File"));
-- return false because it's not our file type
return false
end
@endcode
----
@since 1.11.3
*/

View File

@ -609,7 +609,7 @@ wslua_filehandler_dump_finish(wtap_dumper *wdh, int *err)
WSLUA_CONSTRUCTOR FileHandler_new(lua_State* L) {
/* Creates a new FileHandler */
#define WSLUA_ARG_FileHandler_new_NAME 1 /* The name of the file type, for display purposes only. E.g., "Wireshark - pcapng" */
#define WSLUA_ARG_FileHandler_new_SHORTNAME 2 /* The file type short name, used as a shortcut in various places. E.g., "pcapng". Note: the name cannot already be in use. */
#define WSLUA_ARG_FileHandler_new_SHORTNAME 2 /* The file type short name, used as a shortcut in various places. E.g., "pcapng". Note: The name cannot already be in use. */
#define WSLUA_ARG_FileHandler_new_DESCRIPTION 3 /* Descriptive text about this file format, for display purposes only */
#define WSLUA_ARG_FileHandler_new_TYPE 4 /* The type of FileHandler, "r"/"w"/"rw" for reader/writer/both, include "m" for magic, "s" for strong heuristic */
@ -837,7 +837,9 @@ WSLUA_ATTRIBUTE_FUNC_SETTER(FileHandler,read);
The called Lua function should return true if the read was successful, or false if it hit an error.
Since 2.4.0, a number is also acceptable to signal success, this allows for reuse of `FileHandler:read`:
@code
[source,lua]
----
local function fh_read(file, capture, frame) ... end
myfilehandler.read = fh_read
@ -850,7 +852,7 @@ WSLUA_ATTRIBUTE_FUNC_SETTER(FileHandler,read);
-- Now try to read one frame
return fh_read(file, capture, frame)
end
@endcode
----
*/
WSLUA_ATTRIBUTE_FUNC_SETTER(FileHandler,seek_read);

View File

@ -136,7 +136,10 @@ static int FrameInfo_get_time (lua_State* L) {
/* WSLUA_ATTRIBUTE FrameInfo_data RW The data buffer containing the packet.
@note This cannot be cleared once set.
[NOTE]
====
This cannot be cleared once set.
====
*/
static int FrameInfo_set_data (lua_State* L) {
FrameInfo fi = checkFrameInfo(L,1);

View File

@ -46,7 +46,7 @@ either expressed or implied, of the FreeBSD Project.
it is often set to IEEE 754 double precision floating point, one cannot store a 64 bit integer
with full precision.
For details, see [[https://wiki.wireshark.org/LuaAPI/Int64]].
For details, see https://wiki.wireshark.org/LuaAPI/Int64.
*/
#define LUATYPE64_STRING_SIZE 21 /* string to hold 18446744073709551615 */
@ -61,7 +61,7 @@ WSLUA_CLASS_DEFINE_BASE(Int64,NOP,0);
/*
`Int64` represents a 64 bit signed integer.
For details, see [[https://wiki.wireshark.org/LuaAPI/Int64]].
For details, see https://wiki.wireshark.org/LuaAPI/Int64.
*/
/* A checkInt64 but that also auto-converts numbers, strings, and UINT64 to a gint64 */
@ -614,7 +614,7 @@ LUALIB_API int Int64_register(lua_State* L) {
WSLUA_CLASS_DEFINE_BASE(UInt64,NOP,0);
/* `UInt64` represents a 64 bit unsigned integer, similar to `Int64`.
For details, see: [[https://wiki.wireshark.org/LuaAPI/Int64]].
For details, see: https://wiki.wireshark.org/LuaAPI/Int64.
*/
/* A checkUInt64 but that also auto-converts numbers, strings, and `Int64` to a guint64. */

View File

@ -305,7 +305,7 @@ static int wslua_instancemeta_index_impl(lua_State *L, gboolean is_getter)
lua_pop(L, 1); /* Remove cfunction from stack */
lua_remove(L, 2); /* Remove key from stack */
/*
* Note: this re-uses the current closure as optimization, exposing
* Note: This re-uses the current closure as optimization, exposing
* its upvalues via pseudo-indices. The alternative is to create a
* new C closure (via lua_call), but this is more expensive.
* Callees should not rely on the availability of the upvalues.
@ -501,7 +501,7 @@ static void wslua_push_attributes(lua_State *L, const wslua_attribute_table *t,
void wslua_register_classinstance_meta(lua_State *L, const wslua_class *cls_def)
{
/* Register metatable for use by class instances. STACK = { MT } */
/* NOTE: the name can be changed as long as luaL_checkudata is also adapted */
/* NOTE: The name can be changed as long as luaL_checkudata is also adapted */
luaL_newmetatable(L, cls_def->name);
if (cls_def->instance_meta) {
wslua_setfuncs(L, cls_def->instance_meta, 0);
@ -554,9 +554,9 @@ void wslua_register_classinstance_meta(lua_State *L, const wslua_class *cls_def)
* This functions basically creates a class (type table) with this structure:
*
* Class = { class_methods }
* Class.__typeof = "Class" -- NOTE: might be removed in future
* Class.__typeof = "Class" -- NOTE: Might be removed in future
* Class.__metatable = { class_meta }
* Class.__metatable.__typeof = "Class" -- NOTE: might be removed in future
* Class.__metatable.__typeof = "Class" -- NOTE: Might be removed in future
* Class.__metatable.__index = function_that_errors_out
* Class.__metatable.__newindex = function_that_errors_out
*

View File

@ -193,7 +193,7 @@ WSLUA_CONSTRUCTOR Listener_new(lua_State* L) {
#define WSLUA_OPTARG_Listener_new_FILTER 2 /* A filter that when matches the `tap.packet` function gets
called (use nil to be called for every packet). */
#define WSLUA_OPTARG_Listener_new_ALLFIELDS 3 /* Whether to generate all fields. (default=false)
Note: this impacts performance. */
Note: This impacts performance. */
const gchar* tap_type = luaL_optstring(L,WSLUA_OPTARG_Listener_new_TAP,"frame");
const gchar* filter = luaL_optstring(L,WSLUA_OPTARG_Listener_new_FILTER,NULL);
@ -251,7 +251,7 @@ compare_dissector_key_name(gconstpointer dissector_a, gconstpointer dissector_b)
WSLUA_CONSTRUCTOR Listener_list (lua_State *L) {
/* Gets a Lua array table of all registered `Listener` tap names.
Note: this is an expensive operation, and should only be used for troubleshooting.
Note: This is an expensive operation, and should only be used for troubleshooting.
@since 1.11.3
*/
@ -303,9 +303,15 @@ WSLUA_METAMETHOD Listener__tostring(lua_State* L) {
2. A `Tvb` object
3. A `tapinfo` table
@code function tap.packet(pinfo,tvb,tapinfo) ... end @endcode
[source,lua]
----
function tap.packet(pinfo,tvb,tapinfo) ... end
----
@note `tapinfo` is a table of info based on the `Listener`'s type, or nil.
[NOTE]
====
`tapinfo` is a table of info based on the `Listener`'s type, or nil.
====
*/
WSLUA_ATTRIBUTE_FUNC_SETTER(Listener,packet);
@ -315,7 +321,10 @@ WSLUA_ATTRIBUTE_FUNC_SETTER(Listener,packet);
When later called by Wireshark, the `draw` function will not be given any arguments.
@code function tap.draw() ... end @endcode
[source,lua]
----
function tap.draw() ... end
----
*/
WSLUA_ATTRIBUTE_FUNC_SETTER(Listener,draw);
@ -323,7 +332,10 @@ WSLUA_ATTRIBUTE_FUNC_SETTER(Listener,draw);
When later called by Wireshark, the `reset` function will not be given any arguments.
@code function tap.reset() ... end @endcode
[source,lua]
----
function tap.reset() ... end
----
*/
WSLUA_ATTRIBUTE_FUNC_SETTER(Listener,reset);

View File

@ -51,8 +51,8 @@ WSLUA_METAMETHOD NSTime__call(lua_State* L) { /* Creates a NSTime object. */
WSLUA_METHOD NSTime_tonumber(lua_State* L) {
/* Returns a Lua number of the `NSTime` representing seconds from epoch
* @since 2.4.0
* */
@since 2.4.0
*/
NSTime nstime = checkNSTime(L,1);
lua_pushnumber(L, (lua_Number)nstime_to_sec(nstime));
WSLUA_RETURN(1); /* The Lua number. */

View File

@ -174,7 +174,7 @@ WSLUA_FUNCTION wslua_register_postdissector(lua_State* L) {
It will be called for every frame after dissection. */
#define WSLUA_ARG_register_postdissector_PROTO 1 /* the protocol to be used as post-dissector. */
#define WSLUA_OPTARG_register_postdissector_ALLFIELDS 2 /* Whether to generate all fields.
Note: this impacts performance (default=false). */
Note: This impacts performance (default=false). */
Proto proto = checkProto(L,WSLUA_ARG_register_postdissector_PROTO);
const gboolean all_fields = wslua_optbool(L, WSLUA_OPTARG_register_postdissector_ALLFIELDS, FALSE);

View File

@ -60,7 +60,7 @@
** b/B - signed/unsigned byte
** h/H - signed/unsigned short
** in/In - signed/unsigned integer of size `n' bytes
Note: unpack of i/I is done to a Lua_number, typically a double,
Note: Unpack of i/I is done to a Lua_number, typically a double,
so unpacking a 64-bit field (i8/I8) will lose precision.
Use e/E to unpack into a Wireshark Int64/UInt64 object/userdata instead.
** e/E - signed/unsigned eight-byte Integer (64bits, long long), to/from Int64/UInt64 object
@ -89,7 +89,7 @@
The Struct class offers basic facilities to convert Lua values to and from C-style structs
in binary Lua strings. This is based on Roberto Ierusalimschy's Lua struct library found
in [[http://www.inf.puc-rio.br/~roberto/struct/]], with some minor modifications as follows:
in http://www.inf.puc-rio.br/~roberto/struct/, with some minor modifications as follows:
* Added support for `Int64`/`UInt64` being packed/unpacked, using 'e'/'E'.
* Can handle 'long long' integers (i8 / I8); though they're converted to doubles.
* Can insert/specify padding anywhere in a struct. ('X' eg. when a string is following a union).
@ -98,7 +98,7 @@
pascal-style strings using '`(`' & '`)`'.
All but the first of those changes are based on an email from Flemming Madsen, on the lua-users
mailing list, which can be found [[http://lua-users.org/lists/lua-l/2009-10/msg00572.html|here]].
mailing list, which can be found http://lua-users.org/lists/lua-l/2009-10/msg00572.html[here].
The main functions are `Struct.pack`, which packs multiple Lua values into a struct-like
Lua binary string; and `Struct.unpack`, which unpacks multiple Lua values from a given
@ -147,12 +147,15 @@
* `++(++' to stop assigning items, and `++)++' start assigning (padding when packing).
* `++=++' to return the current position / offset.
@note Using `i`, `I`, `h`, `H`, `l`, `L`, `f`, and `T` is strongly discouraged, as those sizes
[NOTE]
====
Using `i`, `I`, `h`, `H`, `l`, `L`, `f`, and `T` is strongly discouraged, as those sizes
are system-dependent. Use the explicitly sized variants instead, such as `i4` or `E`.
@note Unpacking of `i`/`I` is done to a Lua number, a double-precision floating point,
Unpacking of `i`/`I` is done to a Lua number, a double-precision floating point,
so unpacking a 64-bit field (`i8`/`I8`) will lose precision.
Use `e`/`E` to unpack into a Wireshark `Int64`/`UInt64` object instead.
====
@since 1.11.3
*/

View File

@ -153,9 +153,11 @@ WSLUA_METHOD TreeItem_add_packet_field(lua_State *L) {
be `ENC_BIG_ENDIAN` or `ENC_LITTLE_ENDIAN`.
The signature of this function:
@code
[source,lua]
----
tree_item:add_packet_field(proto_field [,tvbrange], encoding, ...)
@endcode
----
In Wireshark version 1.11.3, this function was changed to return more than
just the new child `TreeItem`. The child is the first return value, so that
@ -177,14 +179,16 @@ WSLUA_METHOD TreeItem_add_packet_field(lua_State *L) {
string encoding types can be used for this, such as `ENC_ASCII` and `ENC_UTF_8`.
For example, assuming the `Tvb` named "`tvb`" contains the string "123":
@code
[source,lua]
----
-- this is done earlier in the script
local myfield = ProtoField.new("Transaction ID", "myproto.trans_id", ftypes.UINT16)
-- this is done inside a dissector, post-dissector, or heuristic function
-- child will be the created child tree, and value will be the number 123 or nil on failure
local child, value = tree:add_packet_field(myfield, tvb:range(0,3), ENC_UTF_8 + ENC_STRING)
@endcode
----
*/
#define WSLUA_ARG_TreeItem_add_packet_field_PROTOFIELD 2 /* The ProtoField field object to add to the tree. */
@ -876,7 +880,7 @@ WSLUA_METHOD TreeItem_referenced(lua_State *L) {
This function takes one parameter that can be a ProtoField or a Dissector. The Dissector form is
usefull when you need to decide whether to call a sub-dissector.
@since 2.4
@since 2.4.0
*/
#define WSLUA_ARG_TreeItem_referenced_PROTOFIELD 2 /* The ProtoField or Dissector to check if referenced. */
TreeItem ti = checkTreeItem(L, 1);

View File

@ -54,9 +54,12 @@ WSLUA_CLASS_DEFINE(Tvb,FAIL_ON_NULL_OR_EXPIRED("Tvb"));
To create a `TvbRange` the `Tvb` must be called with offset and length as optional arguments;
the offset defaults to 0 and the length to `tvb:len()`.
@warning Tvbs are usable only by the current listener or dissector call and are destroyed
[WARNING]
====
Tvbs are usable only by the current listener or dissector call and are destroyed
as soon as the listener/dissector returns, so references to them are unusable once the function
has returned.
====
*/
static GPtrArray* outstanding_Tvb = NULL;
@ -1131,8 +1134,11 @@ WSLUA_METHOD TvbRange_bytes(lua_State* L) {
On failure or error, nil is returned for both return values.
@note The encoding type of the hex string should also be set, for example
[NOTE]
====
The encoding type of the hex string should also be set, for example
`ENC_ASCII` or `ENC_UTF_8`, along with `ENC_STR_HEX`.
====
*/
#define WSLUA_OPTARG_TvbRange_bytes_ENCODING 2 /* An optional ENC_* encoding value to use */
TvbRange tvbr = checkTvbRange(L,1);

View File

@ -55,7 +55,9 @@ WSLUA_FUNCTION wslua_set_plugin_info(lua_State* L) {
by other strings are ignored, and do not cause an error.
Example:
@code
[source,lua]
----
local my_info = {
version = "1.0.1",
author = "Jane Doe",
@ -63,7 +65,7 @@ WSLUA_FUNCTION wslua_set_plugin_info(lua_State* L) {
}
set_plugin_info(my_info)
@endcode
----
@since 1.99.8
*/