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

Added Examples.md for new users #601

Merged
merged 4 commits into from Apr 21, 2021
Merged

Conversation

TheNeoStormZ
Copy link
Contributor

I have made a simple Java file (JSONExamples.java, ubicated in src/main/java/org.json) in which i explain how to get started with all the JSON-types and how to use all conversors to new-comers.

@kushieda-minori
Copy link

kushieda-minori commented Apr 2, 2021

Please rename the file EXAMPLES.md and place in the root of the project. Also surround the code with

```java
package org.json;
import java.util.HashMap;
import java.util.Map;
import java.util.Properties;

//This class' intention is to explain to new-comers the basics of this project
public class JSONExamples {
    // ACTUAL EXAMPLES HERE
}
```

We don't really want the examples compiled into the release jar. Having it as a Markdown file will also make it easy to read.

Copy link
Contributor

@johnjaylward johnjaylward left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

move to a markdown file.

pablo-marin-gomez-us and others added 2 commits April 2, 2021 19:28
Changed JSONExamples to a Markdown file (and another place) with mino…
@TheNeoStormZ
Copy link
Contributor Author

Done! It should be changed now. I have also tweaked the file a little bit so it looks good in Markdown

@stleary
Copy link
Owner

stleary commented Apr 3, 2021

What problem does this code solve?
Project needs documentation to help new users come up to speed.

Risks
None, but need to review the code for syntax, clarity, completeness.

Changes to the API?
No

Will this require a new release?
No

Should the documentation be updated?
Yes, the new markdown file will need to be navigable from the README.

Does it break the unit tests?
No

Was any code refactored in this commit?
No

Review status
ACCEPTED

@TheNeoStormZ TheNeoStormZ changed the title Added some examples for new-comers in a .java file Added some examples for new-comers in a Markdown file Apr 4, 2021
@stleary
Copy link
Owner

stleary commented Apr 18, 2021

@TheNeoStormZ Nice work, thanks for putting in the effort.

This PR is approved. Noting here some possible improvements for future pull requests:

  • I think JSONExampleTokener is incomplete, throws an exception.
  • JavaDocs should be written for the functions
  • An enclosing class should be provided, e.g. JSONJavaDemo.
  • .md headers and text should be commented, so that users can easily copy and paste the entire document into a Java file. For example, // Part 2: Conversion methods
  • The function calls in main() should all be uncommented
  • Additional text should be provided explaining the purpose of each class.
  • Text should be included on how to compile and run this code
  • Add these mandatory imports:
import org.json.CDL;
import org.json.Cookie;
import org.json.HTTP;
import org.json.JSONArray;
import org.json.JSONObject;
import org.json.JSONStringer;
import org.json.JSONTokener;
import org.json.JSONWriter;
import org.json.Property;
import org.json.XML;

@TheNeoStormZ TheNeoStormZ reopened this Apr 18, 2021
@stleary stleary merged commit fa46da4 into stleary:master Apr 21, 2021
@stleary stleary changed the title Added some examples for new-comers in a Markdown file Added Examples.md for new users Dec 5, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

5 participants