Author: Virgil Dupras <email@example.com>
Date: Fri, 8 Jul 2022 07:37:38 -0400
Update the annotation section and add a new idea: accelerators.
|M||NEXTSTEPS.md|| | ||47||+++++++++++++++++------------------------------|
1 file changed, 17 insertions(+), 30 deletions(-)
diff --git a/NEXTSTEPS.md b/NEXTSTEPS.md
@@ -6,38 +6,25 @@ improve in periphery of that main effort.
## Word annotations
I'd like documentation about words to be in-system and this could be done with
-an annotation system. We would add a new 4b field to the dict entry and this
-would be a link to an annotation structure or 0 if none.
+an annotation system. The annotation system is already there, we would need to
+populate those annotations.
-What would be nice is that because non-static C functions are Forth words,
-annotations would work for them too.
+Then, it's a matter of developing a nice interactive application to navigate
+words and see their associated documentation.
-Another idea I have is that this annotation system could automatically pick up
-comments around the word. Example:
- \ This is a docstring
- : myword ( a b -- c d ) \ this was an argspec
+Right now, only one type of annotation is there, the docstring. However, another
+type of annotation would be useful, argspecs. To have comments like ( a b -- n )
+be in a separate structure is not only for better doc formatting, it's also that
+it will eventually be essential for C code to call Forth words. Because the C
+compiler has to know the signature of a word to properly call it, we'll need
+that argpec annotation to have a "machine-readable" structure.
-Word from kernel and boot don't have annotations, but what sys/annotate.fs
-could do is add annotations for all kernel+boot words at load time. It could
-also override ( and \ word so that they copy the contents of the comments
-somewhere instead of discarding them so that they can be processed for
-1b annotation type
-3b element length
-4b next annotation element or 0
-a list of parameters and return values. A machine-readable equivalent to
-stuff like "( a b -- c d )". Could be used by the C compiler to check
-Documentation text for the word. Could be printed (along with ARGSPEC) by words
-like "doc myword".
+It would be fun if assemblers were leveraged early in the boot process to
+accelerate some core words. For example, it could override the "+" word into an
+immediate that emits `eax [ebp] mov, ebp 4 i32 add, [ebp] eax add,`, or even
+better, that detects if the last compiled word was a literal and replace that
+literal with `[ebp] (replaced literal) i32 add,`.