From 6275508a1842bf1afe16c0906e4160e52cbdb660 Mon Sep 17 00:00:00 2001 From: ChillerDragon Date: Sun, 13 Nov 2022 13:31:52 +0100 Subject: [PATCH] Documentation refactor --- README.md | 2 +- docs/v0.0.1/README.md | 36 +++++ docs/v0.0.1/classes/ChatMessage.md | 7 + docs/v0.0.1/classes/Context.md | 62 +++++++++ docs/v0.0.1/classes/Player.md | 11 ++ .../classes/TeeworldsClient.md} | 127 +++--------------- scripts/hooks.sh | 12 +- 7 files changed, 146 insertions(+), 111 deletions(-) create mode 100644 docs/v0.0.1/README.md create mode 100644 docs/v0.0.1/classes/ChatMessage.md create mode 100644 docs/v0.0.1/classes/Context.md create mode 100644 docs/v0.0.1/classes/Player.md rename docs/{v0.0.1.md => v0.0.1/classes/TeeworldsClient.md} (56%) diff --git a/README.md b/README.md index fa575f3..d30563d 100644 --- a/README.md +++ b/README.md @@ -38,4 +38,4 @@ client.connect('localhost', 8303, detach: false) ## Documentation -Checkout [docs/v0.0.1.md](docs/v0.0.1.md) for a full library documentation. +Checkout [docs/v0.0.1/READE.md](docs/v0.0.1/README.md) for a full library documentation. diff --git a/docs/v0.0.1/README.md b/docs/v0.0.1/README.md new file mode 100644 index 0000000..dafd75d --- /dev/null +++ b/docs/v0.0.1/README.md @@ -0,0 +1,36 @@ +# teeworlds_network + +Version v0.0.1 + +## Classes + +### [ChatMessage](classes/ChatMessage.md) + +### [Context](classes/Context.md) + +### [Player](classes/Player.md) + +### [TeeworldsClient](classes/TeeworldsClient.md) + +[#on_snapshot(&block)](classes/TeeworldsClient.md#on_snapshot) + +[#on_rcon_line(&block)](classes/TeeworldsClient.md#on_rcon_line) + +[#on_disconnect(&block)](classes/TeeworldsClient.md#on_disconnect) + +[#on_connected(&block)](classes/TeeworldsClient.md#on_connected) + +[#on_client_info(&block)](classes/TeeworldsClient.md#on_client_info) + +[#on_chat(&block)](classes/TeeworldsClient.md#on_chat) + +[#on_map_change(&block)](classes/TeeworldsClient.md#on_map_change) + +[#on_client_drop(&block)](classes/TeeworldsClient.md#on_client_drop) + +[#connect(ip, port, options)](classes/TeeworldsClient.md#connect) + +[#send_chat(str)](classes/TeeworldsClient.md#send_chat) + + + diff --git a/docs/v0.0.1/classes/ChatMessage.md b/docs/v0.0.1/classes/ChatMessage.md new file mode 100644 index 0000000..b456d2e --- /dev/null +++ b/docs/v0.0.1/classes/ChatMessage.md @@ -0,0 +1,7 @@ +# ChatMessage + +### @mode [Integer] +### @client_id [Integer] +### @target_id [Integer] +### @message [Integer] +### @author [[Player](../classes/Player.md)] \ No newline at end of file diff --git a/docs/v0.0.1/classes/Context.md b/docs/v0.0.1/classes/Context.md new file mode 100644 index 0000000..a09b86f --- /dev/null +++ b/docs/v0.0.1/classes/Context.md @@ -0,0 +1,62 @@ +# Context + +This class is the callback context. +When you hook into methods using a ``on_*`` method you can access its context. +This gives you the ability to read and modify the data before the default behavior processes it. +Or skip the default behavior and implement your own logic. + +### #cancle + +Call the ``cancle()`` on the context object to not run any default code for that event. + +```ruby +client.on_map_change do |context| + # do nothing when a map change packet comes in + # skips the send ready packet code + context.cancle +end +``` + +### @client [[TeeworldsClient](../classes/TeeworldsClient.md)] + +Access the network client to send packets. + +**Example:** + +Reimplement your on on_connected logic and cancle the default one + +```ruby +client.on_connected do |ctx| + ctx.client.send_msg_start_info + ctx.cancle +end +``` + +### @data [Hash] + +This hash holds all the current data. They keys might vary depending on the current context. +You can read and write those values. If you set an unused key the program will panic. + +**Example:** + +Here an example to see what keys you are given for a client info event. + +```ruby +client = TeeworldsClient.new + +client.on_client_info do |context| + p context.data.keys + # [:player, :chunk] +end +``` + +Here an example to modify all incoming player info to rename all player objects to yee. +Which is a bit weird but shows the power of the modding api. + +```ruby +client = TeeworldsClient.new + +client.on_client_info do |context| + context.data[:player].name = 'yee' +end +``` \ No newline at end of file diff --git a/docs/v0.0.1/classes/Player.md b/docs/v0.0.1/classes/Player.md new file mode 100644 index 0000000..ed8dfc2 --- /dev/null +++ b/docs/v0.0.1/classes/Player.md @@ -0,0 +1,11 @@ +# Player + +### @id [Integer] +### @local [Integer] +### @team [Integer] +### @name [String] +### @clan [String] +### @country [Integer] +### @skin_parts [Array#String] +### @skin_custom_colors [Array#Integer] +### @skin_colors [Array#Integer] \ No newline at end of file diff --git a/docs/v0.0.1.md b/docs/v0.0.1/classes/TeeworldsClient.md similarity index 56% rename from docs/v0.0.1.md rename to docs/v0.0.1/classes/TeeworldsClient.md index 750f9ee..01c7ffc 100644 --- a/docs/v0.0.1.md +++ b/docs/v0.0.1/classes/TeeworldsClient.md @@ -1,93 +1,8 @@ -# Classes +# TeeworldsClient -## Player +### #on_snapshot(&block) -### @id [Integer] -### @local [Integer] -### @team [Integer] -### @name [String] -### @clan [String] -### @country [Integer] -### @skin_parts [Array#String] -### @skin_custom_colors [Array#Integer] -### @skin_colors [Array#Integer] - -## ChatMessage - -### @mode [Integer] -### @client_id [Integer] -### @target_id [Integer] -### @message [Integer] -### @author [[Player](#player)] - -## Context - -This class is the callback context. -When you hook into methods using a ``on_*`` method you can access its context. -This gives you the ability to read and modify the data before the default behavior processes it. -Or skip the default behavior and implement your own logic. - -### #cancle - -Call the ``cancle()`` on the context object to not run any default code for that event. - -```ruby -client.on_map_change do |context| - # do nothing when a map change packet comes in - # skips the send ready packet code - context.cancle -end -``` - -### @client [[TeeworldsClient](#teeworldsclient)] - -Access the network client to send packets. - -**Example:** - -Reimplement your on on_connected logic and cancle the default one - -```ruby -client.on_connected do |ctx| - ctx.client.send_msg_start_info - ctx.cancle -end -``` - -### @data [Hash] - -This hash holds all the current data. They keys might vary depending on the current context. -You can read and write those values. If you set an unused key the program will panic. - -**Example:** - -Here an example to see what keys you are given for a client info event. - -```ruby -client = TeeworldsClient.new - -client.on_client_info do |context| - p context.data.keys - # [:player, :chunk] -end -``` - -Here an example to modify all incoming player info to rename all player objects to yee. -Which is a bit weird but shows the power of the modding api. - -```ruby -client = TeeworldsClient.new - -client.on_client_info do |context| - context.data[:player].name = 'yee' -end -``` - -## TeeworldsClient - -### #on_snapshot(&block) - -**Parameter: block [Block |[context](#context)|]** +**Parameter: block [Block |[context](../classes/Context.md)|]** TODO: generated documentation @@ -102,9 +17,9 @@ end client.connect('localhost', 8303, detach: true) ``` -### #on_rcon_line(&block) +### #on_rcon_line(&block) -**Parameter: block [Block |[context](#context)|]** +**Parameter: block [Block |[context](../classes/Context.md)|]** TODO: generated documentation @@ -119,9 +34,9 @@ end client.connect('localhost', 8303, detach: true) ``` -### #on_disconnect(&block) +### #on_disconnect(&block) -**Parameter: block [Block |[context](#context)|]** +**Parameter: block [Block |[context](../classes/Context.md)|]** TODO: generated documentation @@ -136,9 +51,9 @@ end client.connect('localhost', 8303, detach: true) ``` -### #on_connected(&block) +### #on_connected(&block) -**Parameter: block [Block |[context](#context)|]** +**Parameter: block [Block |[context](../classes/Context.md)|]** TODO: generated documentation @@ -153,9 +68,9 @@ end client.connect('localhost', 8303, detach: true) ``` -### #on_client_info(&block) +### #on_client_info(&block) -**Parameter: block [Block |[context](#context)|]** +**Parameter: block [Block |[context](../classes/Context.md)|]** TODO: generated documentation @@ -170,12 +85,12 @@ end client.connect('localhost', 8303, detach: true) ``` -### #on_chat(&block) +### #on_chat(&block) -**Parameter: block [Block |[ChatMessage](#chatmessage)|]** +**Parameter: block [Block |[ChatMessage](../classes/ChatMessage.md)|]** Takes a block that will be called when the client receives a chat message. -The block takes one parameter of type [ChatMessage](#chatmessage). +The block takes one parameter of type [ChatMessage](../classes/ChatMessage.md). **Example:** @@ -188,9 +103,9 @@ end client.connect('localhost', 8303, detach: true) ``` -### #on_map_change(&block) +### #on_map_change(&block) -**Parameter: block [Block |[context](#context)|]** +**Parameter: block [Block |[context](../classes/Context.md)|]** Takes a block that will be called when the client receives a map change packet. @@ -210,13 +125,13 @@ end client.connect('localhost', 8303, detach: true) ``` -### #on_client_drop(&block) +### #on_client_drop(&block) -**Parameter: block [Block |[context](#context)|]** +**Parameter: block [Block |[context](../classes/Context.md)|]** Takes a block that will be called when the client receives a client drop packet. -Context: +Context.data: ```ruby [ @@ -240,7 +155,7 @@ end ``` -### connect(ip, port, options) +### #connect(ip, port, options) **Parameter: ip [String]** @@ -269,7 +184,7 @@ client.connect('localhost', 8303, detach: false) ``` -### send_chat(str) +### #send_chat(str) **Parameter: str [String]** diff --git a/scripts/hooks.sh b/scripts/hooks.sh index 38f4aca..40edb45 100755 --- a/scripts/hooks.sh +++ b/scripts/hooks.sh @@ -35,7 +35,7 @@ function add_hook_doc() { echo "Error: failed to generate docs! File not found $mdfile" exit 1 fi - class_ln="$(grep -n "## $ruby_class" "$mdfile" | cut -d':' -f1)" + class_ln="$(grep -n "^# $ruby_class" "$mdfile" | cut -d':' -f1)" class_ln="$((class_ln+1))" if [ "$class_ln" == "" ] then @@ -56,10 +56,14 @@ function add_hook_doc() { tmpdoc="$tmpdir/doc.md" { head -n "$class_ln" "$mdfile" + # the ancor tag is a hack to allow linking + # methods using #hook_name + # because we want to put junk after the hook name + # for example the parameters cat <<- EOF - ### #$hook(&block) + ### #$hook(&block) - **Parameter: block [Block |[context](#context)|]** + **Parameter: block [Block |[context](../classes/Context.md)|]** TODO: generated documentation @@ -111,7 +115,7 @@ function check_file() { echo -n "[*] checking hook: $hook" # check documentation local mdfile - mdfile="docs/$version.md" + mdfile="docs/$version/classes/$ruby_class.md" if [ ! -f "$mdfile" ] then echo "ERROR: documentation not found $mdfile"