Fix documentation of port API (#2312)

The patch fixes both the doc comments in the port header and the
corresponding markdown documentation.

The patch also removes an internal configuration macro guard
exposed by the public port header.

JerryScript-DCO-1.0-Signed-off-by: Akos Kiss akiss@inf.u-szeged.hu

1 files changed, 24 insertions, 7 deletions

diff --git a/docs/05.PORT-API.md b/docs/05.PORT-API.md
index c5cb98f4..9a7cd82b 100644
--- a/docs/05.PORT-API.md
+++ b/docs/05.PORT-API.md
@@ -11,7 +11,8 @@ It is questionable whether a library should be able to terminate an application.
  *
  * @param code gives the cause of the error.
  *
- * Note: jerry expects the function not to return.
+ * Note:
+ *      Jerry expects the function not to return.
  *
  * Example: a libc-based port may implement this with exit() or abort(), or both.
  */
@@ -81,14 +82,25 @@ typedef struct
 /**
  * Get timezone and daylight saving data
  *
+ * Note:
+ *      This port function is called by jerry-core when
+ *      CONFIG_DISABLE_DATE_BUILTIN is _not_ defined. Otherwise this function is
+ *      not used.
+ *
  * @return true  - if success
  *         false - otherwise
  */
-bool jerry_port_get_time_zone (jerry_time_zone_t *);
+bool jerry_port_get_time_zone (jerry_time_zone_t *tz_p);
 
 /**
  * Get system time
  *
+ * Note:
+ *      This port function is called by jerry-core when
+ *      CONFIG_DISABLE_DATE_BUILTIN is _not_ defined. It is also common practice
+ *      in application code to use this function for the initialization of the
+ *      random number generator.
+ *
  * @return milliseconds since Unix epoch
  */
 double jerry_port_get_current_time (void);
@@ -100,12 +112,13 @@ Allow user to provide external buffer for jerry instance (which includes an isol
 
 ```c
 /**
- * Get the current instance, which contains the current context, heap and other infomation.
- * Each port should provide its own implementation of this interface.
+ * Get the current instance which contains the current context, heap and other
+ * structures. Each port should provide its own implementation of this interface.
  *
- *Note:
- *    This port function will be called automatically by jerry-core
- *    when JERRY_ENABLE_EXTERNAL_CONTEXT is defined. If not, this function will never be called.
+ * Note:
+ *      This port function is called by jerry-core when
+ *      JERRY_ENABLE_EXTERNAL_CONTEXT is defined. Otherwise this function is not
+ *      used.
  *
  * @return the pointer to the jerry instance.
  */
@@ -117,6 +130,10 @@ struct jerry_instance_t *jerry_port_get_current_instance (void);
 ```c
 /**
  * Makes the process sleep for a given time.
+ *
+ * Note:
+ *      This port function is called by jerry-core when JERRY_DEBUGGER is
+ *      defined. Otherwise this function is not used.
  */
 void jerry_port_sleep (uint32_t sleep_time);
 ```