Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

The type json is missing from the html documentation #1616

Closed
piotrklos-tcl opened this issue May 31, 2019 · 4 comments
Closed

The type json is missing from the html documentation #1616

piotrklos-tcl opened this issue May 31, 2019 · 4 comments

Comments

@piotrklos-tcl
Copy link

  • What is the issue you have?

The examples in the README mention type json as the most basic type to use by default in order to use the library. The problem is that the linked documentation https://nlohmann.github.io/json/classnlohmann_1_1basic__json.html does not document this type.
This is certain to confuse anyone newbie. I'm willing to bet a beer that you are loosing 20% of newcomers because of this, particularly those who are new to C++.

Note: This is not about whether I can find the information for myself. I found out from the code that json is defined as "using json= basic_json<>;" and looked up the docs of basic_json. This is a quality of documentation issue that affects others.

  • Please describe the steps to reproduce the issue. Can you provide a small but working code example?

Look at the README and try to use the library. Then try to look up members of type json in https://nlohmann.github.io/json/classnlohmann_1_1basic__json.html.

  • What is the expected behavior?

I expect https://nlohmann.github.io/json/classnlohmann_1_1basic__json.html to contain documentation of the json type (for example mentioning that json is a typedef for basic_json).

  • And what is the actual behavior instead?

https://nlohmann.github.io/json/classnlohmann_1_1basic__json.html does not document the name json.

all OSes and compilers

  • Did you use a released version of the library or the version from the develop branch?

The released version.

no

@nlohmann
Copy link
Owner

nlohmann commented Jun 1, 2019

This is the first time I heard of someone asking for documentation of the json type. Right now, it is this: https://nlohmann.github.io/json/namespacenlohmann_a2bfd99e845a2e5cd90aeaf1b1431f474.html#a2bfd99e845a2e5cd90aeaf1b1431f474

What do you expect instead?

@piotrklos-tcl
Copy link
Author

One correction: When I copied the documentation link, I meant https://nlohmann.github.io/json/, not https://nlohmann.github.io/json/classnlohmann_1_1basic__json.html. I'm not sure where the latter came from. So I meant that your html documentation in general doesn't have the json typedef documented.
You link https://nlohmann.github.io/json/namespacenlohmann_a2bfd99e845a2e5cd90aeaf1b1431f474.html#a2bfd99e845a2e5cd90aeaf1b1431f474, and it is indeed there, I stand corrected in that respect. I didn't find it at the time though and I still think this is a usability issue.
Neither the main docs page (https://nlohmann.github.io/json/index.html) nor README links to it. You can find it by typing it into the search bar on the docs page, but I can't find it through google.

This is the first time I heard of someone asking for documentation of the json type.

I don't think that it is a particularly good measure of a need in a situation when everyone who doesn't find what he's looking for has a ton of alternative libraries. I understand how you could think that in the absence of other feedback though.

What do you expect instead?

I thing you should link to this type (json, not basic_json) from as many places as possible, because this is the central type to your library. From my experience in the industry, the people who don't really know C++ but need to use it outnumber those who really know it 5 to 1. They won't automatically know that json is basic_json.

@nlohmann
Copy link
Owner


🔖 Release item

This issue/PR will be part of the next release of the library. This template helps preparing the release notes.

Type

  • ✨ New Feature
  • 🐛 Bug Fix
  • ⚡️ Improvement
  • 🔨 Further Change
  • 🔥 Deprecated function

Description

  • Mention json type on the documentation start page.

@nlohmann
Copy link
Owner

I added a note to the API documentation. It will be part of the next release.

@nlohmann nlohmann modified the milestones: Release 3.6.2, Release 3.7.0 Jul 9, 2019
@nlohmann nlohmann added this to the Release 3.7.0 milestone Jul 28, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants