String-returning _customDump overload is too useful to be non-public

[pyrtsa]

When looking at call sites of customDump(...) in TCA, it strikes me that the most common use (in committed code anyway) must be with the inout String parameter variant, customDump(_:to:...).

The downside of that is it turns what could be a one-line expression into three lines of code, every time:

var output = ""
customDump(value, to: &output)
return output  // or use output in some further string interpolation for example

Disregarding the fact that Swift.dump(...) also has the same shortcoming, why not consider making the String returning counterpart _customDump(...) public, just like diff(...) is public and returns String?

The function could be slightly renamed to stand apart—but not too far—from the existing two, e.g.

@discardableResult
public func customDump<T>(_ value: T, name: String? = nil, indent: Int = 0, maxDepth: Int = .max) -> T

@discardableResult
public func customDump<T, TargetStream>(
  _ value: T, to target: inout TargetStream, name: String? = nil, indent: Int = 0, maxDepth: Int = .max
) -> T where TargetStream: TextOutputStream

// 👇  New addition:

public func customDumped(_ value: Any, name: String? = nil, indent: Int = 0, maxDepth: Int = .max) -> String

// ☝️

[stephencelis]

@pyrtsa I think we're definitely down to explore this. It's just a matter of coming up with the right name:

• customDumped is a good contender, though reads kinda funny as a function
• customDumpOutput is a way we describe the string in various repos
• customDumpDescription could be a riff on that

We'll think on it and open the floor to other suggestions. In the meantime, defining a helper in your projects isn't the end of the world, though we admit it is annoying 😄

[pyrtsa]

Maybe a bit long but I don't dislike customDumpDescription either, FWIW! 👍