Improve docs_writer.cpp

1 files changed, 23 insertions, 1 deletions

diff --git a/core/math/big/internal.odin b/core/math/big/internal.odin
index 5085898e5..dbcd16509 100644
--- a/core/math/big/internal.odin
+++ b/core/math/big/internal.odin
@@ -1,10 +1,32 @@
-//+ignore
 /*
 	Copyright 2021 Jeroen van Rijn <nom@duclavier.com>.
 	Made available under Odin's BSD-3 license.
+
+	==========================    Low-level routines    ==========================
+
+	IMPORTANT: `internal_*` procedures make certain assumptions about their input.
+
+	The public functions that call them are expected to satisfy their sanity check requirements.
+	This allows `internal_*` call `internal_*` without paying this overhead multiple times.
+
+	Where errors can occur, they are of course still checked and returned as appropriate.
+
+	When importing `math:core/big` to implement an involved algorithm of your own, you are welcome
+	to use these procedures instead of their public counterparts.
+
+	Most inputs and outputs are expected to be passed an initialized `Int`, for example.
+	Exceptions include `quotient` and `remainder`, which are allowed to be `nil` when the calling code doesn't need them.
+
+	Check the comments above each `internal_*` implementation to see what constraints it expects to have met.
+
+	We pass the custom allocator to procedures by default using the pattern `context.allocator = allocator`.
+	This way we don't have to add `, allocator` at the end of each call.
+
+	TODO: Handle +/- Infinity and NaN.
 */
 
 
+//+ignore
 package math_big
 
 import "core:mem"