Update command-line-interface.md explanation of (@main). (#59573)

Explain in simple terms the usage of `(@main)` and note that the return
value must be an `Int32` or `nothing`, in the docs.

Related to: #58984

---------

Co-authored-by: Neven Sajko <4944410+nsajko@users.noreply.github.com>
Co-authored-by: Lilith Orion Hafner <lilithhafner@gmail.com>

Author: 3 people

doc/src/manual/command-line-interface.md

@@ -46,8 +46,24 @@ but at the conclusion of executing a script or expression, `julia` will attempt
 `Main.main(Base.ARGS)` if such a function `Main.main` has been defined and this behavior was opted into
 by using the `@main` macro.
 
-This feature is intended to aid in the unification
-of compiled and interactive workflows. In compiled workflows, loading the code that defines the `main`
+To see this feature in action, consider the following definition:
+```julia
+(@main)(args) = println("Hello $(args[1])!")
+```
+Executing the above script with `julia script.jl "Buddy"` will automatically run `(@main)` and print "Hello Buddy!",
+despite there being no explicit call to `(@main)`.
+
+The return value of the `(@main)` function must either be `nothing`, resulting in exit code
+`0`, or convertible to a `Cint` which will be the exit code:
+```
+$ julia -e "(@main)(args) = nothing"; echo $?0
+0
+$ julia -e "(@main)(args) = 1"; echo $?
+1
+```
+Typically exit codes are in the range `0:255`, although the interpretation of the return value might be OS dependent.
+
+This feature is intended to aid in the unification of compiled and interactive workflows. In compiled workflows, loading the code that defines the `main`
 function may be spatially and temporally separated from the invocation. However, for interactive workflows,
 the behavior is equivalent to explicitly calling `exit(main(ARGS))` at the end of the evaluated script or
 expression.
@@ -56,14 +72,6 @@ expression.
     The special entry point `Main.main` was added in Julia 1.11. For compatibility with prior julia versions,
     add an explicit `@isdefined(var"@main") ? (@main) : exit(main(ARGS))` at the end of your scripts.
 
-To see this feature in action, consider the following definition, which will execute the print function despite there being no explicit call to `main`:
-
-```
-$ julia -e '(@main)(args) = println("Hello World!")'
-Hello World!
-$
-```
-
 Only the `main` binding in the `Main` module has this behavior and only if
 the macro `@main` was used within the defining module.