Add further clarity to example package

Makefile

@@ -193,7 +193,8 @@ include test/dsp/core/test.mk
 include test/dsp/scale/test.mk
 include test/dsp/tty/test.mk
 include test/dsp/test.mk
-include third_party/make/build.mk
+include examples/package/lib/build.mk
+include examples/package/build.mk
 #-φ-examples/package/new.sh
 include test/test.mk
 

README.md

@@ -83,7 +83,7 @@ by typing `C-c C-h` with the cursor over a symbol. Please install these:
     emacs                            # for power and glory!
 
 See [tool/emacs/cosmo-stuff.el] for further details. Further note that
-this codebase might seem to have an usual number of include statements
+this codebase might seem to have unusual numbers of include statements
 quoted and vendored code, but that's actually why the tools work since
 it gives them easy perfect knowledge of what exists, thus performance.
 

examples/examples.mk

@@ -115,4 +115,6 @@ o/$(MODE)/examples/hellojs.com.dbg:			\
 	@$(APELINK)
 
 .PHONY: o/$(MODE)/examples
-o/$(MODE)/examples: $(EXAMPLES_BINS)
+o/$(MODE)/examples:					\
+		o/$(MODE)/examples/package		\
+		$(EXAMPLES_BINS)

examples/package/lib/build.mk

@@ -20,7 +20,7 @@
 # EXAMPLE
 #
 #   make o//examples/package/lib  # build library w/ sanity checks
-#   at t o//examples/package/lib/lib.a
+#   ar t o//examples/package/lib/lib.a
 #
 # AUTHORS
 #
@@ -28,19 +28,22 @@
 
 PKGS += EXAMPLES_PACKAGE_LIB
 
-# Declares build package.
-# Other packages may list this variable in their deps list.
-# Please note package relationships aren't allowed to be cyclic.
+# Declares package i.e. library w/ transitive dependencies.
+# We define packages as a thing that lumps similar sources.
+# It's needed, so linkage can have a higher level overview.
+# Mostly due to there being over 9,000 objects in the repo.
 EXAMPLES_PACKAGE_LIB =						\
 	$(EXAMPLES_PACKAGE_LIB_A_DEPS)				\
 	$(EXAMPLES_PACKAGE_LIB_A)
 
-# While build configs might seem somewhat complicated but rest
-# assured they're mostly maintainence free, thanks to wildcard
-EXAMPLES_PACKAGE_LIB_A_FILES := $(wildcard examples/package/lib/*)
-EXAMPLES_PACKAGE_LIB_ARTIFACTS += EXAMPLES_PACKAGE_LIB_A
-EXAMPLES_PACKAGE_LIB_A_HDRS = $(filter %.h,$(EXAMPLES_PACKAGE_LIB_A_FILES))
+# Declares library w/o transitive dependencies.
 EXAMPLES_PACKAGE_LIB_A = o/$(MODE)/examples/package/lib/lib.a
+EXAMPLES_PACKAGE_LIB_ARTIFACTS += EXAMPLES_PACKAGE_LIB_A
+
+# Build configs might seem somewhat complicated. Rest assured they're
+# mostly maintainence free. That's largely thanks to how we wildcard.
+EXAMPLES_PACKAGE_LIB_A_FILES := $(wildcard examples/package/lib/*)
+EXAMPLES_PACKAGE_LIB_A_HDRS = $(filter %.h,$(EXAMPLES_PACKAGE_LIB_A_FILES))
 
 # Define sets of source files without needing further iops.
 EXAMPLES_PACKAGE_LIB_A_SRCS_S =					\
@@ -57,6 +60,7 @@ EXAMPLES_PACKAGE_LIB_A_OBJS =					\
 	$(EXAMPLES_PACKAGE_LIB_A_SRCS_C:%.c=o/$(MODE)/%.o)	\
 	$(EXAMPLES_PACKAGE_LIB_A_SRCS:%=o/$(MODE)/%.zip.o)
 
+# Does the two most important things for C/C++ code sustainability.
 # 1. Guarantees each header builds, i.e. includes symbols it needs.
 # 2. Guarantees transitive closure of packages is directed acyclic.
 EXAMPLES_PACKAGE_LIB_A_CHECKS =					\

examples/package/lib/myasm.S

@@ -1,6 +1,16 @@
 #include "libc/macros.h"
 
-MyAsm:	.leafprologue
+/	Example assembly function.
+/
+/	@note	param agnostic
+/	@note	we love stack frames
+/		easiest way to do backtraces
+/		somehow they usually make code faster
+/		it's convention for keeping stack 16-byte aligned
+/		cpus still devote much to pushing & popping b/c i386
+MyAsm:	push	%rbp
+	mov	%rsp,%rbp
 	call	MyPrint2
-	.leafepilogue
+	pop	%rbp
+	ret
 	.endfn	MyAsm,globl

examples/package/lib/myprint.c

@@ -1,10 +1,19 @@
 #include "examples/package/lib/myprint.h"
 #include "libc/stdio/stdio.h"
 
+/**
+ * Calls MyPrint2() indirected via assembly function.
+ */
 void MyPrint(const char *s) {
   MyAsm(s);
 }
 
+/**
+ * Prints string to output.
+ *
+ * @param s is null-terminated c string usually having \n
+ * @see printf() which has domain-specific language
+ */
 void MyPrint2(const char *s) {
   fputs(s, stdout);
 }