mkdir: make mkdir public and document it

[KAAtheWiseGit]

• Made the mkdir function public. Added documentation, describing the behavior and parameters
• Moved the GNU dot-stripping behavior from exec to mkdir.

[KAAtheWiseGit]

@tertsdiepraam, opened the PR. It doesn't have much as of now, since I haven't made mkdir public.

[sylvestre]

Suggested change

	/// * `recurisve` --- create parent directories for the given dirs, if they do
	/// * `recursive` --- create parent directories for the given dirs, if they do

[tertsdiepraam]

Thanks for opening the PR! For context for others, we were talking here: #5321.

---

A little recap:

The question is: what should be exposed? exec or mkdir?

• exec: makes multiple directories and some GNU behaviour fix.
• mkdir: makes a single directory.

Multiple directories is usually not good for nushell, because they what control over the errors and make them pretty with miette. So, we prefer not to print errors but to return them (with Result). Another question is whether the GNU behaviour is expected by nushell.

---

With that out of the way, here are my thoughts. I think it makes sense to expose a function for making a single directory and let nushell do the looping for good errors. I also think the GNU fix at least doesn't hurt for nushell, so I see no reason to exclude it.

So, in my opinion, the GNU fix is in the wrong spot: it should be in mkdir and then we can expose that.

[KAAtheWiseGit]

Rewrote the commit:

• Made mkdir public instead of exec.
• Completed the documentation GNU behavior note.
• Moved the GNU patch into mkdir.

Changed the PR name/description appropriately.

[KAAtheWiseGit]

I think the PR is ready for review.

[tertsdiepraam]

I won't merge this myself because I'm reviewing from the GH app, but this looks great!

[tertsdiepraam]

Great comment here!

[cakebaker]

Thanks :)