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.

[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.