Add warning about the old std.json module from D1

[wilzbach]

We shouldn't advertise code like this:

JSONValue json = parseJSON(`{"foo": 1}`);
auto a = &(json.object());
json.uinteger = 0;
(*a)["hello"] = 1;

https://run.dlang.io/is/KW86zH

https://dlang.org/phobos/std_json.html

[dlang-bot]

Thanks for your pull request, @wilzbach!

Bugzilla references

Your PR doesn't reference any Bugzilla issue.

If your PR contains non-trivial changes, please reference a Bugzilla issue or create a manual changelog.

Testing this PR locally

If you don't have a local development environment setup, you can use Digger to test this PR:

dub fetch digger
dub run digger -- build "master + phobos#6111"

[JackStouffer]

I don't know about this. I know that people come into the Learn group and and are confused about the status of std.xml and want to know what to do. While these modules aren't fast or pretty, they do work while the linked modules do not. I don't think we should worry users about the stability of these modules when we don't have a road-map to replacing them. What we currently have are modules which might replace the Phobos versions if someone picks up the torch.

[quickfur]

I suppose we should just do this to prevent people wasting time pouring their energy into this module when it's slated to be replaced.

However, I really would prefer seeing concrete evidence that std.data.json is on its way into Phobos, before putting up signs like this one. Is integration of std.data.json into Phobos being actively worked on? If not, aren't we just setting ourselves up for bad rep with modules that are deprecated but year after year remain without replacement?

[andralex]

A mention of the upcoming package is worthwhile, but we do not lay judgment.

[JackStouffer]

AFAIK Sönke has stopped working on std.data.json to focus on vibe.d (last commit was almost a year ago). That's why I said we need someone to pick up the torch before we start endorsing it.

[quickfur]

Yeah, if nobody is actively working on std.data.json, then we shouldn't be advertising it in the Phobos docs.

[CyberShadow]

auto a = &(json.object());

BTW, I think we can fix this example by making JSONValue not use unions. It will use more memory, but it will be safe. I think that's more important for Phobos.

[wilzbach]

Yeah, if nobody is actively working on std.data.json, then we shouldn't be advertising it in the Phobos docs.

Hmm, how should somebody pick up the torch if they don't know about it?
I reworded that sentence and also used the nicer message boxes:

For std.xml:

[andralex]

Folks, this is really simple. If we have a definite existing or upcoming replacement in the standard library, we can advertise it. If we invite others to work on one, that's nice to mention too. A "see also" section somewhere? Fine, too. Otherwise the standard library isn't in the business of passing judgment about itself. This is not open for negotiation.

[JackStouffer]

@wilzbach Adding a simple see also section to the top with a link to Sönke's library that states

For an alternative JSON library, see ...

seems like the best option here.