update the docs

doc/docs.md

@@ -6107,7 +6107,7 @@ sure that the access index will be valid.
 
 #### `[packed]`
 
-The `[packed]` attribute can be added to a structure to create an unaligned memory layout,
+The `[packed]` attribute can be applied to a structure to create an unaligned memory layout,
 which decreases the overall memory footprint of the structure. Using the `[packed]` attribute
 may negatively impact performance or even be prohibited on certain CPU architectures.
 
@@ -6122,18 +6122,42 @@ is needed.
 
 #### `[aligned]`
 
-The `[aligned]` attribute can be added to a structure to specify a minimum alignment (in bytes). 
-Using the `[aligned]` attribute you can increase the alignment, when using `[packed]` you can 
-decrease it.
+The `@[aligned]` attribute can be applied to a structure or union to specify a minimum alignment
+(in bytes) for variables of that type. Using the `@[aligned]` attribute you can only *increase*
+the default alignment. 
+Use `@[packed]` you want to *decrease* it. The alignment of any struct or union, should be at
+least a perfect multiple of the lowest common multiple of the alignments of all of the members
+of the struct or union.
 
+Example:
+```v
+// Each u16 in the `data` field below, takes 2 bytes, and we have 3 of them = 6 bytes.
+// The smallest power of 2, bigger than 6 is 8, i.e. with `@[aligned]`, the alignment
+// for the entire struct U16s, will be 8:
+@[aligned]
+struct U16s {
+	data [3]u16
+}
+```
 **When to Use**
 
-- When memory usage is more critical than performance, e.g., in embedded systems.
+- Only if the instances of your types, will be used in performance critical sections, or with
+specialised machine instructions, that do require a specific alignment to work.
 
 **When to Avoid**
 
-- On CPU architectures that do not support unaligned memory access or when high-speed memory access
-is needed.
+- On CPU architectures, that do not support unaligned memory access. If you are not working on
+performance critical algorithms, you do not really need it, since the proper minimum alignment
+is CPU specific.
+
+You can leave out the alignment factor, i.e. use just `@[aligned]`, in which case the compiler
+will align a type to the maximum useful alignment for the target machine you are compiling for,
+i.e. the alignment will be the largest alignment which is ever used for any data type on the
+target machine. Doing this can often make copy operations more efficient, because the compiler
+can choose whatever instructions copy the biggest chunks of memory, when performing copies to or
+from the variables which have types that you have aligned this way.
+
+See also ["What Every Programmer Should Know About Memory", by Ulrich Drepper](https://people.freebsd.org/~lstewart/articles/cpumemory.pdf) .
 
 #### `[minify]`
 
@@ -7133,4 +7157,4 @@ Assignment Operators
 +=   -=   *=   /=   %=
 &=   |=   ^=
 >>=  <<=  >>>=
-```
+```