From 7f23abbf8cdb4516eb302e4b0e0b3198039ce5b3 Mon Sep 17 00:00:00 2001
From: Subhomoy Haldar <hungrybluedev@gmail.com>
Date: Sun, 25 Sep 2022 17:36:01 +0100
Subject: [PATCH] docs: document the [noinit] attribute with an example
 (#15876)

---
 cmd/tools/vcheck-md.v   | 12 ++++++++++-
 cmd/v/help/check-md.txt |  5 +++--
 doc/docs.md             | 48 ++++++++++++++++++++++++++++++++++++++++-
 3 files changed, 61 insertions(+), 4 deletions(-)

diff --git a/cmd/tools/vcheck-md.v b/cmd/tools/vcheck-md.v
index bb362609bd..722e09e051 100644
--- a/cmd/tools/vcheck-md.v
+++ b/cmd/tools/vcheck-md.v
@@ -541,6 +541,16 @@ fn (mut f MDFile) check_examples() CheckResult {
 					}
 					oks++
 				}
+				'okfmt' {
+					if fmt_res != 0 {
+						eprintln(eline(f.path, e.sline, 0, 'okfmt example is not formatted'))
+						eprintln(vcontent)
+						should_cleanup_vfile = false
+						errors++
+						continue
+					}
+					oks++
+				}
 				'badsyntax' {
 					res := silent_cmdexecute('${os.quoted_path(vexe)} -w -Wfatal-errors -check-syntax ${os.quoted_path(vfile)}')
 					if res == 0 {
@@ -554,7 +564,7 @@ fn (mut f MDFile) check_examples() CheckResult {
 				}
 				'nofmt' {}
 				else {
-					eprintln(eline(f.path, e.sline, 0, 'unrecognized command: "$command", use one of: wip/ignore/compile/cgen/failcompile/oksyntax/badsyntax/nofmt'))
+					eprintln(eline(f.path, e.sline, 0, 'unrecognized command: "$command", use one of: wip/ignore/compile/cgen/failcompile/okfmt/oksyntax/badsyntax/nofmt'))
 					should_cleanup_vfile = false
 					errors++
 				}
diff --git a/cmd/v/help/check-md.txt b/cmd/v/help/check-md.txt
index ad58f74528..cc1d7d1dec 100644
--- a/cmd/v/help/check-md.txt
+++ b/cmd/v/help/check-md.txt
@@ -17,7 +17,8 @@ These are:
 	live         - Compile hot reload examples with the ´-live´ flag set and verify formatting.
 	ignore       - Ignore the example, useful for examples that just use the syntax highlighting
 	failcompile  - Known failing compilation. Useful for examples demonstrating compiler errors.
-	oksyntax     - Should parse and be formatted but may not compile. Useful for partial examples.
-	badsyntax    - Known bad syntax, it should not even parse.
+	okfmt        - Should only be formatted, but it can refer to invalid modules, missing functions etc. Useful for partial examples.
+	oksyntax     - Should parse, and be formatted, but may not compile. Useful for partial examples.
+	badsyntax    - Known bad syntax, it should NOT even parse.
 	wip          - Like ignore; a planned feature; easy to search.
 	nofmt        - Disable fmt verification for individual code blocks.
diff --git a/doc/docs.md b/doc/docs.md
index 50d34f97d7..75fdec27f7 100644
--- a/doc/docs.md
+++ b/doc/docs.md
@@ -139,7 +139,7 @@ To do so, run the command `v up`.
 
 <!--
 NB: there are several special keywords, which you can put after the code fences for v:
-compile, cgen, live, ignore, failcompile, oksyntax, badsyntax, wip, nofmt
+compile, cgen, live, ignore, failcompile, okfmt, oksyntax, badsyntax, wip, nofmt
 For more details, do: `v check-md`
 -->
 
@@ -2139,6 +2139,52 @@ assert book.author.name == 'Samantha Black'
 assert book.author.age == 24
 ```
 
+### `[noinit]` structs
+
+V supports `[noinit]` structs, which are structs that cannot be initialised outside the module
+they are defined in. They are either meant to be used internally or they can be used externally
+through _factory functions_.
+
+For an example, consider the following source in a directory `sample`:
+
+```v oksyntax
+module sample
+
+[noinit]
+pub struct Information {
+pub:
+	data string
+}
+
+pub fn new_information(data string) !Information {
+	if data.len == 0 || data.len > 100 {
+		return error('data must be between 1 and 100 characters')
+	}
+	return Information{
+		data: data
+	}
+}
+```
+
+Note that `new_information` is a _factory_ function. Now when we want to use this struct
+outside the module:
+
+```v okfmt
+import sample
+
+fn main() {
+	// This doesn't work when the [noinit] attribute is present:
+	// info := sample.Information{
+	// 	data: 'Sample information.'
+	// }
+
+	// Use this instead:
+	info := sample.new_information('Sample information.')!
+
+	println(info)
+}
+```
+
 ### Methods
 
 ```v