Improve ability documentation

packages/warriorjs-abilities/src/attack.js

@@ -3,15 +3,17 @@ import { BACKWARD, FORWARD } from '@warriorjs/geography';
 const defaultDirection = FORWARD;
 
 function attack({ power }) {
+  const backwardPower = Math.ceil(power / 2.0);
   return unit => ({
     action: true,
-    description: `Attacks a unit in the given direction (\`'${defaultDirection}'\` by default), dealing ${power} HP of damage.`,
+    argumentsDescription: `direction = '${defaultDirection}'`,
+    description: `Attacks a unit in the given direction (${defaultDirection} by default), dealing ${power} HP of damage in any direction except backward (reduced to ${backwardPower} if attacking backward).`,
     perform(direction = defaultDirection) {
       const receiver = unit.getSpaceAt(direction).getUnit();
       if (receiver) {
         unit.log(`attacks ${direction} and hits ${receiver}`);
         const attackingBackward = direction === BACKWARD;
-        const amount = attackingBackward ? Math.ceil(power / 2.0) : power;
+        const amount = attackingBackward ? backwardPower : power;
         unit.damage(receiver, amount);
       } else {
         unit.log(`attacks ${direction} and hits nothing`);

packages/warriorjs-abilities/src/attack.test.js

@@ -20,7 +20,7 @@ describe('attack', () => {
 
   test('has a description', () => {
     expect(attack.description).toBe(
-      `Attacks a unit in the given direction (\`'${FORWARD}'\` by default), dealing 3 HP of damage.`,
+      `Attacks a unit in the given direction (${FORWARD} by default), dealing 3 HP of damage in any direction except backward (reduced to 2 if attacking backward).`,
     );
   });
 

packages/warriorjs-abilities/src/bind.js

@@ -5,7 +5,8 @@ const defaultDirection = FORWARD;
 function bind() {
   return unit => ({
     action: true,
-    description: `Binds a unit in the given direction (\`'${defaultDirection}'\` by default) to keep him from moving.`,
+    argumentsDescription: `direction = '${defaultDirection}'`,
+    description: `Binds a unit in the given direction (${defaultDirection} by default) to keep him from moving.`,
     perform(direction = defaultDirection) {
       const receiver = unit.getSpaceAt(direction).getUnit();
       if (receiver) {

packages/warriorjs-abilities/src/bind.test.js

@@ -17,7 +17,7 @@ describe('bind', () => {
 
   test('has a description', () => {
     expect(bind.description).toBe(
-      `Binds a unit in the given direction (\`'${FORWARD}'\` by default) to keep him from moving.`,
+      `Binds a unit in the given direction (${FORWARD} by default) to keep him from moving.`,
     );
   });
 

packages/warriorjs-abilities/src/detonate.js

@@ -6,7 +6,8 @@ const surroundingOffsets = [[1, 1], [1, -1], [2, 0], [0, 0]];
 function detonate({ targetPower, surroundingPower }) {
   return unit => ({
     action: true,
-    description: `Detonates a bomb in a given direction (\`'${defaultDirection}'\` by default), dealing ${targetPower} HP of damage to that space and ${surroundingPower} HP of damage to surrounding 4 spaces (including yourself).`,
+    argumentsDescription: `direction = '${defaultDirection}'`,
+    description: `Detonates a bomb in a given direction (${defaultDirection} by default), dealing ${targetPower} HP of damage to that space and ${surroundingPower} HP of damage to surrounding 4 spaces (including yourself).`,
     perform(direction = defaultDirection) {
       unit.log(`detonates a bomb ${direction} launching a deadly explosion`);
       const targetSpace = unit.getSpaceAt(direction);

packages/warriorjs-abilities/src/detonate.test.js

@@ -21,7 +21,7 @@ describe('detonate', () => {
 
   test('has a description', () => {
     expect(detonate.description).toBe(
-      `Detonates a bomb in a given direction (\`'${FORWARD}'\` by default), dealing 4 HP of damage to that space and 2 HP of damage to surrounding 4 spaces (including yourself).`,
+      `Detonates a bomb in a given direction (${FORWARD} by default), dealing 4 HP of damage to that space and 2 HP of damage to surrounding 4 spaces (including yourself).`,
     );
   });
 

packages/warriorjs-abilities/src/directionOf.js

@@ -2,7 +2,7 @@ import { BACKWARD, FORWARD, LEFT, RIGHT } from '@warriorjs/geography';
 
 function directionOf() {
   return unit => ({
-    description: `Returns the direction (${FORWARD}, ${RIGHT}, ${BACKWARD} or ${LEFT}) to the given space.`,
+    description: `Returns the direction (\`'${FORWARD}'\`, \`'${RIGHT}'\`, \`'${BACKWARD}'\` or \`'${LEFT}'\`) to the given space.`,
     perform(space) {
       return unit.getDirectionOf(space);
     },

packages/warriorjs-abilities/src/directionOf.test.js

@@ -17,7 +17,7 @@ describe('directionOf', () => {
 
   test('has a description', () => {
     expect(directionOf.description).toBe(
-      `Returns the direction (${FORWARD}, ${RIGHT}, ${BACKWARD} or ${LEFT}) to the given space.`,
+      `Returns the direction (\`'${FORWARD}'\`, \`'${RIGHT}'\`, \`'${BACKWARD}'\` or \`'${LEFT}'\`) to the given space.`,
     );
   });
 

packages/warriorjs-abilities/src/directionOfStairs.js

@@ -2,7 +2,7 @@ import { BACKWARD, FORWARD, LEFT, RIGHT } from '@warriorjs/geography';
 
 function directionOfStairs() {
   return unit => ({
-    description: `Returns the direction (${FORWARD}, ${RIGHT}, ${BACKWARD} or ${LEFT}) the stairs are from your location.`,
+    description: `Returns the direction (\`'${FORWARD}'\`, \`'${RIGHT}'\`, \`'${BACKWARD}'\` or \`'${LEFT}'\`) the stairs are from your location.`,
     perform() {
       return unit.getDirectionOfStairs();
     },

packages/warriorjs-abilities/src/directionOfStairs.test.js

@@ -17,7 +17,7 @@ describe('directionOfStairs', () => {
 
   test('has a description', () => {
     expect(directionOfStairs.description).toBe(
-      `Returns the direction (${FORWARD}, ${RIGHT}, ${BACKWARD} or ${LEFT}) the stairs are from your location.`,
+      `Returns the direction (\`'${FORWARD}'\`, \`'${RIGHT}'\`, \`'${BACKWARD}'\` or \`'${LEFT}'\`) the stairs are from your location.`,
     );
   });
 

packages/warriorjs-abilities/src/feel.js

@@ -4,7 +4,8 @@ const defaultDirection = FORWARD;
 
 function feel() {
   return unit => ({
-    description: `Returns the adjacent space in the given direction (\`'${defaultDirection}'\` by default).`,
+    argumentsDescription: `direction = '${defaultDirection}'`,
+    description: `Returns a \`Space\` object for the adjacent space in the given direction (${defaultDirection} by default).`,
     perform(direction = defaultDirection) {
       return unit.getSensedSpaceAt(direction);
     },

packages/warriorjs-abilities/src/feel.test.js

@@ -17,7 +17,7 @@ describe('feel', () => {
 
   test('has a description', () => {
     expect(feel.description).toBe(
-      `Returns the adjacent space in the given direction (\`'${FORWARD}'\` by default).`,
+      `Returns a \`Space\` object for the adjacent space in the given direction (${FORWARD} by default).`,
     );
   });
 

packages/warriorjs-abilities/src/listen.js

@@ -3,7 +3,7 @@ import { FORWARD, getRelativeOffset } from '@warriorjs/geography';
 function listen() {
   return unit => ({
     description:
-      'Returns an array of all spaces which have units in them (excluding yourself).',
+      'Returns an array of all `Space`s which have units in them (excluding yourself).',
     perform() {
       return unit
         .getOtherUnits()

packages/warriorjs-abilities/src/listen.test.js

@@ -27,7 +27,7 @@ describe('listen', () => {
 
   test('has a description', () => {
     expect(listen.description).toBe(
-      'Returns an array of all spaces which have units in them (excluding yourself).',
+      'Returns an array of all `Space`s which have units in them (excluding yourself).',
     );
   });
 

packages/warriorjs-abilities/src/look.js

@@ -4,7 +4,8 @@ const defaultDirection = FORWARD;
 
 function look({ range }) {
   return unit => ({
-    description: `Returns an array of up to ${range} spaces in the given direction (\`'${defaultDirection}'\` by default).`,
+    argumentsDescription: `direction = '${defaultDirection}'`,
+    description: `Returns an array of up to ${range} \`Space\`s in the given direction (${defaultDirection} by default).`,
     perform(direction = defaultDirection) {
       const offsets = Array.from(new Array(range), (_, index) => index + 1);
       const spaces = offsets.map(offset =>

packages/warriorjs-abilities/src/look.test.js

@@ -17,7 +17,7 @@ describe('look', () => {
 
   test('has a description', () => {
     expect(look.description).toBe(
-      `Returns an array of up to 3 spaces in the given direction (\`'${FORWARD}'\` by default).`,
+      `Returns an array of up to 3 \`Space\`s in the given direction (${FORWARD} by default).`,
     );
   });
 

packages/warriorjs-abilities/src/pivot.js

@@ -5,7 +5,8 @@ const defaultDirection = BACKWARD;
 function pivot() {
   return unit => ({
     action: true,
-    description: `Rotates in the given direction (\`'${defaultDirection}'\` by default).`,
+    argumentsDescription: `direction = '${defaultDirection}'`,
+    description: `Rotates in the given direction (${defaultDirection} by default).`,
     perform(direction = defaultDirection) {
       unit.rotate(direction);
       unit.log(`pivots ${direction}`);

packages/warriorjs-abilities/src/pivot.test.js

@@ -20,7 +20,7 @@ describe('pivot', () => {
 
   test('has a description', () => {
     expect(pivot.description).toBe(
-      `Rotates in the given direction (\`'${BACKWARD}'\` by default).`,
+      `Rotates in the given direction (${BACKWARD} by default).`,
     );
   });
 

packages/warriorjs-abilities/src/rescue.js

@@ -5,7 +5,8 @@ const defaultDirection = FORWARD;
 function rescue() {
   return unit => ({
     action: true,
-    description: `Releases a unit from his chains in the given direction (\`'${defaultDirection}'\` by default).`,
+    argumentsDescription: `direction = '${defaultDirection}'`,
+    description: `Releases a unit from his chains in the given direction (${defaultDirection} by default).`,
     perform(direction = defaultDirection) {
       const receiver = unit.getSpaceAt(direction).getUnit();
       if (receiver && receiver.isBound()) {

packages/warriorjs-abilities/src/rescue.test.js

@@ -20,7 +20,7 @@ describe('rescue', () => {
 
   test('has a description', () => {
     expect(rescue.description).toBe(
-      `Releases a unit from his chains in the given direction (\`'${FORWARD}'\` by default).`,
+      `Releases a unit from his chains in the given direction (${FORWARD} by default).`,
     );
   });
 

packages/warriorjs-abilities/src/rest.js

@@ -2,7 +2,7 @@ function rest({ healthGain }) {
   const healthGainPercentage = healthGain * 100;
   return unit => ({
     action: true,
-    description: `Gains ${healthGainPercentage}% of max health back, but does nothing more.`,
+    description: `Gains ${healthGainPercentage}% of max health back (rounded half-up to the nearest integer), but does nothing more.`,
     perform() {
       if (unit.health < unit.maxHealth) {
         unit.log('rests');

packages/warriorjs-abilities/src/rest.test.js

@@ -20,7 +20,7 @@ describe('rest', () => {
 
   test('has a description', () => {
     expect(rest.description).toBe(
-      'Gains 10% of max health back, but does nothing more.',
+      'Gains 10% of max health back (rounded half-up to the nearest integer), but does nothing more.',
     );
   });
 

packages/warriorjs-abilities/src/shoot.js

@@ -5,7 +5,8 @@ const defaultDirection = FORWARD;
 function shoot({ power, range }) {
   return unit => ({
     action: true,
-    description: `Shoots the bow & arrow in the given direction (\`'${defaultDirection}'\` by default), dealing ${power} HP of damage to the first unit in a range of ${range} spaces.`,
+    argumentsDescription: `direction = '${defaultDirection}'`,
+    description: `Shoots the bow & arrow in the given direction (${defaultDirection} by default), dealing ${power} HP of damage to the first unit in a range of ${range} spaces.`,
     perform(direction = defaultDirection) {
       const offsets = Array.from(new Array(range), (_, index) => index + 1);
       const receiver = offsets

packages/warriorjs-abilities/src/shoot.test.js

@@ -20,7 +20,7 @@ describe('shoot', () => {
 
   test('has a description', () => {
     expect(shoot.description).toBe(
-      `Shoots the bow & arrow in the given direction (\`'${FORWARD}'\` by default), dealing 3 HP of damage to the first unit in a range of 3 spaces.`,
+      `Shoots the bow & arrow in the given direction (${FORWARD} by default), dealing 3 HP of damage to the first unit in a range of 3 spaces.`,
     );
   });
 

packages/warriorjs-abilities/src/think.js

@@ -2,6 +2,7 @@ import util from 'util';
 
 function think() {
   return unit => ({
+    argumentsDescription: `thought`,
     description: 'Thinks out loud (`console.log` replacement).',
     perform(...args) {
       const thought = args.length > 0 ? util.format(...args) : 'nothing';

packages/warriorjs-abilities/src/walk.js

@@ -5,7 +5,8 @@ const defaultDirection = FORWARD;
 function walk() {
   return unit => ({
     action: true,
-    description: `Moves one space in the given direction (\`'${defaultDirection}'\` by default).`,
+    argumentsDescription: `direction = '${defaultDirection}'`,
+    description: `Moves one space in the given direction (${defaultDirection} by default).`,
     perform(direction = defaultDirection) {
       const space = unit.getSpaceAt(direction);
       if (space.isEmpty()) {

packages/warriorjs-abilities/src/walk.test.js

@@ -20,7 +20,7 @@ describe('walk', () => {
 
   test('has a description', () => {
     expect(walk.description).toBe(
-      `Moves one space in the given direction (\`'${FORWARD}'\` by default).`,
+      `Moves one space in the given direction (${FORWARD} by default).`,
     );
   });
 

packages/warriorjs-cli/templates/readme/ability.ejs

@@ -1 +1 @@
-- `warrior.<%- ability.name %>()`: <%- ability.description -%>
+- `warrior.<%- ability.name %>(<%- ability.argumentsDescription %>)`: <%- ability.description -%>

packages/warriorjs-core/src/Warrior.js

@@ -38,9 +38,10 @@ class Warrior extends Unit {
    */
   getAbilities() {
     const abilities = [...this.abilities].map(
-      ([name, { action, description }]) => ({
+      ([name, { action, argumentsDescription, description }]) => ({
         name,
         action,
+        argumentsDescription,
         description,
       }),
     );

packages/warriorjs-core/src/getLevel.test.js

@@ -26,14 +26,14 @@ const levelConfig = {
       abilities: {
         walk: () => ({
           action: true,
-          description: `Moves one space in the given direction (\`'${FORWARD}'\` by default).`,
+          description: `Moves one space in the given direction (${FORWARD} by default).`,
         }),
         attack: () => ({
           action: true,
-          description: `Attacks a unit in the given direction (\`'${FORWARD}'\` by default), dealing 5 HP of damage.`,
+          description: `Attacks a unit in the given direction (${FORWARD} by default), dealing 5 HP of damage.`,
         }),
         feel: () => ({
-          description: `Returns the adjacent space in the given direction (\`'${FORWARD}'\` by default).`,
+          description: `Returns the adjacent space in the given direction (${FORWARD} by default).`,
         }),
       },
       position: {
@@ -51,10 +51,10 @@ const levelConfig = {
         abilities: {
           attack: () => ({
             action: true,
-            description: `Attacks a unit in the given direction (\`'${FORWARD}'\` by default), dealing 3 HP of damage.`,
+            description: `Attacks a unit in the given direction (${FORWARD} by default), dealing 3 HP of damage.`,
           }),
           feel: () => ({
-            description: `Returns the adjacent space in the given direction (\`'${FORWARD}'\` by default).`,
+            description: `Returns the adjacent space in the given direction (${FORWARD} by default).`,
           }),
         },
         playTurn(sludge) {
@@ -145,19 +145,19 @@ test('returns level', () => {
         {
           name: 'attack',
           description:
-            "Attacks a unit in the given direction (`'forward'` by default), dealing 5 HP of damage.",
+            'Attacks a unit in the given direction (forward by default), dealing 5 HP of damage.',
         },
         {
           name: 'walk',
           description:
-            "Moves one space in the given direction (`'forward'` by default).",
+            'Moves one space in the given direction (forward by default).',
         },
       ],
       senses: [
         {
           name: 'feel',
           description:
-            "Returns the adjacent space in the given direction (`'forward'` by default).",
+            'Returns the adjacent space in the given direction (forward by default).',
         },
       ],
     },