Repository navigation
docs: add Javadoc for the public API - #14
Merged
Merged
Conversation
IDEs and the generated HTML showed nothing for the main interfaces. This describes MultiMap, CommentedMap, OptionMap, Profile, Persistable, Configurable, Registry and the exceptions: value conversion, variable syntax, the section tree, and what load and store do with streams and flags. Each statement was checked against the implementations. Refs: #13
Config has about 45 public constants and an accessor pair for each option, and nothing explained what a flag changes. Each option is now described once at its getter, with its default and system property, after checking how the parsers, formatters and maps use it. Refs: #13
The default implementations differ from what the interfaces suggest in a few places: remove returns the first value, entrySet is a snapshot, a comment stays when a key is removed through keySet, and the global Config limits variable nesting. These are now written down. Refs: #13
Ini, Wini, Options, Reg, ConfigParser and the java.util.prefs classes had no type docs. This adds them, with the encoding and byte order mark rules and the Windows-only registry methods. The old IniPreferences text said childSpi and childrenNamesSpi were unsupported, which the code contradicts, so it is rewritten, and its typos and the broken @PARem tag are fixed. Refs: #13
The handler call order, the comment timing and the provider lookup were only visible in the code. This writes them down for the parsers, the formatters and the two handler interfaces, checked against logs of real parse runs. Refs: #13
How a parsed file becomes sections, options and comments (which comment is kept, which is lost, what the header comment is) was not written down anywhere. This documents it for the Ini, Reg and Options builders. Refs: #13
The escape forms, the registry value encoding and the rules of the bean proxy were undocumented, and several have edge cases (empty registry strings, unquote with stray backslashes, Object methods on a proxy). These are written down after running each case. Refs: #13
ServiceFinder had Hungarian Javadoc with lost accents that also described a parameter that no longer exists. It is rewritten in English from the code. IniSource and the byte order mark reader get short docs because their rules (comment timing, pushback) are not obvious. Refs: #13
The two package.html files said ini4j has a single package and did not explain the model. They become package-info.java with a glossary, an example and the provider lookup. The javadoc plugin now runs with doclint all,-missing and fails the build, and CI uploads the generated HTML as an artifact so a reviewer can read it. Refs: #13
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The public API of
org.ini4jandorg.ini4j.spihad almost no Javadoc, so IDEs and the generated HTML showed nothing useful for the main interfaces and forConfig. This adds it, mostly in the order a reader needs it: the core contracts, everyConfigoption, the base implementations, the user-facing classes, the SPI parsers, formatters and builders, and the escape and bean utilities. The Hungarian text inServiceFinderis translated, typos in comments are fixed, and the twopackage.htmlfiles becomepackage-info.javawith a glossary and an example.Each statement was checked against the code, and the edge cases by running small programs. Where the code does something surprising, for example
OptionMap.fetch(Object, String)not resolving variables, the Javadoc says so and the behavior is unchanged. The Java changes are comments only: the compiled classes are identical before and after.The javadoc plugin now runs with doclint
all,-missingand fails the build on a broken reference or tag. CI also uploadstarget/apidocs/as an artifact so the HTML can be read from a PR.Refs #13