added license information to main code files.v0.0.2

added comments to the code.

added readme (very similar to the fossil wiki page, just for completeness).

FossilOrigin-Name: 7d5413782349944209dea2a447563c5e3ac817ebdb01822d3f87a33423a1f5d8

1 files changed, 69 insertions, 3 deletions

diff --git a/nimisewi.c b/nimisewi.c
index 34623d0..de2fed9 100644
--- a/nimisewi.c
+++ b/nimisewi.c
@@ -1,3 +1,31 @@
+/* Copyright (c) 2021, la-ninpre
+ * 
+ * Permission to use, copy, modify, and/or distribute this software for any
+ * purpose with or without fee is hereby granted, provided that the above
+ * copyright notice and this permission notice appear in all copies.
+ * 
+ * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ *
+ * *************************************************************************
+ * 
+ * this file contains main code for nimisewi.
+ * 
+ * nimisewi is a small program that generates random toki pona noun phrase.
+ * toki pona is a small constructed language created by sonja lang 
+ * (see https://tokipona.org).
+ *
+ * functions and variables here a primarily named in tokipona, just because i
+ * can. but just in case there are annotations in english.
+ *
+ * sona nanpa li ike. taso ona li pali e nimi pona.
+ */
+
 #include <err.h>
 #include <stdio.h>
 #include <stdlib.h>
@@ -10,7 +38,14 @@
 #include "nimitoki.h" /* nimi_toki, suli_pi_nimi_toki */
 
 void
-open_e_nanpa_sewi() {
+open_e_nanpa_sewi()
+{
+    /* initialize pseudorandom generator using pid, microseconds and seconds
+     *
+     * for such silly program there's no need to implement cryptographically
+     * secure random number generator.
+     */
+
     pid_t pid;
     struct timeval time;
 
@@ -24,6 +59,23 @@ const char
              const int suli_pi_nimi_mute,
              const int nanpa_nimi)
 {
+    /* wrapper function to get word from array
+     *
+     * noun phrases in toki pona could have arbitrary amount of words and they
+     * are left grouped (the leftmost word is main, and words to the right
+     * are modifying it:
+     *
+     * ((nimi) sewi)
+     *
+     * special word 'pi' could be used to alter this grouping order to achieve
+     * something like english preposition 'of'
+     *
+     * ((suli) pi ((nimi) mute))
+     *
+     * this functions inserts 'pi' in the middle to avoid generating
+     * very heavy phrases.
+     */
+
     if (nanpa_nimi > suli_pi_nimi_mute) {
         err(EXIT_FAILURE, "index out of bounds");
     } else if (nanpa_nimi == -1) {
@@ -36,6 +88,11 @@ const char
 void
 pana_e_nanpa_nimi(struct nanpa_nimi *nn)
 {
+    /* generate random number, which is later used as number of words
+     * in the phrase
+     *
+     * also here is made decision, whether to insert 'pi'
+     */
     nn->pi_li_lon = 0;
     nn->nanpa_pi = -1;
     nn->nanpa_nimi = (rand() % 6);
@@ -56,6 +113,11 @@ pana_e_nanpa_pi_nimi_sewi(int *nanpa_sewi_mute,
                           const int suli_nimi,
                           struct nanpa_nimi *nn)
 {
+    /* create specified amount of random numbers
+     *
+     * they are used later as indices to get words from wordlist
+     */
+
     int i;
 
     for (i = 0; i <= nn->nanpa_nimi; i++) {
@@ -70,9 +132,9 @@ pana_e_nanpa_pi_nimi_sewi(int *nanpa_sewi_mute,
 int
 main(void)
 {
-    int *nanpa_sewi_nimi;
+    int *nanpa_sewi_nimi; /* container for random indices */
     int i;
-    struct nanpa_nimi nn;
+    struct nanpa_nimi nn; /* see nimisewi.h */
 
 #ifdef __OpenBSD__
     if (pledge("stdio", NULL) == -1) {
@@ -90,6 +152,10 @@ main(void)
 
     pana_e_nanpa_pi_nimi_sewi(nanpa_sewi_nimi, suli_pi_nimi_toki, &nn);
 
+    /* i think that this section could be improved. i had an idea that
+     * it would be cool to include options to output in cgi format instead
+     * of just text
+     */
     for (i = 0; i < nn.nanpa_nimi; i++) {
         printf("%s ",
                 pana_e_nimi(nimi_toki, suli_pi_nimi_toki, nanpa_sewi_nimi[i]));