commit 8d1c02de8d0442db3a691b9d4a6218f382c836c4
from: Benjamin Stürz <benni@stuerz.xyz>
date: Fri Nov 15 23:47:15 2024 UTC

make: implement doc comments

commit - ad926673f59ad05775df2ef71f78dabcba0dc048
commit + 8d1c02de8d0442db3a691b9d4a6218f382c836c4
blob - b140f120cbc92d105ddc893e9a468b23bce4e55d
blob + c59972a7534d5fa93068452e7ae3cee97ab1ed57
--- make/MyMakefile
+++ make/MyMakefile
@@ -1,15 +1,19 @@
+## Installation prefix
 PREFIX ?= /usr
 CFLAGS = -g -O0 -ansi -Wall -Wno-deprecated-non-prototype -Wno-comment -Wno-implicit-int
 
 all: make
 
+## Install make into ${DESTDIR}${PREFIX}/bin/make.
 install: make
 	mkdir -p ${DESTDIR}${PREFIX}/bin
 	cp -f make ${DESTDIR}${PREFIX}/bin/
 
+## Remove any build artifacts.
 clean:
 	rm -f make *.core
 
+## Run make.
 run: make
 	./make
 
blob - fb7db528948ded17772f6914fa42f8ba2ab912e9
blob + 242c3a778f41dc2423a249d69e6160f4e73f4870
--- make/TODO.md
+++ make/TODO.md
@@ -70,23 +70,6 @@ CFLAGS = -ansi
 CFLAGS += -Wall
 ```
 
-
-# Doc comments for help page
-```make
-## build the code base
-all: a b
-
-## delete build artifacts
-clean:
-
-## build component "a"
-a:
-
-## build component "b"
-b:
-```
-
-
 # Templates
 ## MyMakefile
 ```make
blob - 68cbd5a361f7280ae0ffd7069be3747a23e12c97
blob + 4710c7c0d8f98cc64b8a9b9a56a2e10fea8b0cd4
--- make/make.c
+++ make/make.c
@@ -664,10 +664,10 @@ char *s;
 }
 
 struct rule *
-parse_rule (sc, dir, s, t)
+parse_rule (sc, dir, s, t, help)
 struct scope *sc;
 struct path *dir;
-char *s, *t;
+char *s, *t, *help;
 {
 	struct inference *inf;
 	struct rule *r;
@@ -733,12 +733,16 @@ char *s, *t;
 				f->deps = deps;
 				f->dtail = dt;
 				f->mtime = get_mtime (path_to_str (dir), f->name);
+				f->help = help;
 				sc->dir->files = f;
 				continue;
 			}
 
 			flag = 0;
 
+			if (f->help == NULL)
+				f->help = help;
+
 			if (f->deps == NULL) {
 				f->deps = deps;
 				f->dtail = dt;
@@ -762,7 +766,7 @@ char *path;
 	struct macro *m, *m2;
 	struct rule *r = NULL;
 	size_t len, cap;
-	char *s, *t;
+	char *s, *t, *help = NULL;
 	FILE *file;
 	int ln = 0;
 
@@ -777,7 +781,11 @@ char *path;
 	}
 
 	for (; (s = readline (file, &ln)) != NULL; free (s)) {
-		if (s[0] == '#' || *trim (s) == '\0') {
+		if (s[0] == '#' && s[1] == '#') {
+			help = strdup (expand (sc, trim (s + 2), NULL));
+			continue;
+		} else if (s[0] == '#' || *trim (s) == '\0') {
+			continue;
 		} else if (starts_with (s, ".include ")) {
 			if (parse_include (sc, dir, s + 9) == -1)
 				errx (1, "%s:%d: syntax error", path, ln);
@@ -786,19 +794,18 @@ char *path;
 
 			for (m = sc->dir->emacros; m != NULL; m = m->enext) {
 				if (strcmp (m->name, t) == 0)
-					goto ok; /* already exported */
+					goto cont; /* already exported */
 			}
 
 			for (m = sc->dir->macros; m != NULL; m = m->next) {
 				if (strcmp (m->name, t) == 0) {
 					m->enext = sc->dir->emacros;
 					sc->dir->emacros = m;
-					goto ok;
+					goto cont;
 				}
 			}
 
 			errx (1, "%s:%d: no such macro: %s", path, ln, t);
-		ok:	;
 		} else if (s[0] == '\t') {
 			if (r == NULL)
 				errx (1, "%s:%d: syntax error", path, ln);
@@ -816,6 +823,7 @@ char *path;
 
 			m = new (struct macro);
 			m->next = sc->dir->macros;
+			m->help = help;
 
 			if (t[-1] == '!') {
 				t[-1] = '\0';
@@ -842,9 +850,9 @@ char *path;
 			m->name = strdup (trim (s));
 			sc->dir->macros = m;
 		} else if ((t = strchr (s, ':')) != NULL) {
-			r = parse_rule (sc, dir, s, t);
+			r = parse_rule (sc, dir, s, t, help);
 			if (r == NULL)
-				continue;
+				goto cont;
 
 			len = 0;
 			cap = 1;
@@ -853,6 +861,9 @@ char *path;
 		} else {
 			warnx ("%s:%d: syntax error", path, ln);
 		}
+
+	cont:
+		help = NULL;
 	}
 
 	return 0;
@@ -1316,12 +1327,16 @@ struct scope *sc;
 		errx (1, "print_sc(): must be of type SC_DIR");
 
 	for (m = sc->dir->macros; m != NULL; m = m->next) {
+		if (m->help != NULL)
+			printf ("\n## %s\n", m->help);
 		printf ("%s = %s\n", m->name, m->value);
 	}
 
 	printf ("\n");
 
 	for (f = sc->dir->files; f != NULL; f = f->next) {
+		if (f->help != NULL)
+			printf ("## %s\n", f->help);
 		printf ("%s:", f->name);
 	
 		for (dep = f->deps; dep != NULL; dep = dep->next)
blob - d2758945c7b2ec8dc2490fe94f889cd012978ab9
blob + a541402897a1d3a09bcd5962f1577a6c923952f8
--- make/make.h
+++ make/make.h
@@ -51,6 +51,7 @@ struct file {
 	struct rule *rule; /* optional */
 	struct dep *deps, *dtail;
 	struct timespec mtime;
+	char *help; /* optional */
 };
 
 struct inference {
@@ -68,6 +69,7 @@ struct macro {
 	struct macro *next, *enext;
 	char *name;
 	char *value;
+	char *help;
 	int lazy;
 };