Skip to content

docs: add Javadoc for the public API - #14

Merged
szkiba merged 9 commits into
mainfrom
javadoc-1-public-api
Nov 16, 2026
Merged

szkiba merged 9 commits into
mainfrom
javadoc-1-public-api

Conversation

@szkiba

@szkiba szkiba commented Nov 16, 2026

Copy link
Copy Markdown
Contributor

The public API of org.ini4j and org.ini4j.spi had almost no Javadoc, so IDEs and the generated HTML showed nothing useful for the main interfaces and for Config. This adds it, mostly in the order a reader needs it: the core contracts, every Config option, the base implementations, the user-facing classes, the SPI parsers, formatters and builders, and the escape and bean utilities. The Hungarian text in ServiceFinder is translated, typos in comments are fixed, and the two package.html files become package-info.java with 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,-missing and fails the build on a broken reference or tag. CI also uploads target/apidocs/ as an artifact so the HTML can be read from a PR.

Refs #13

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
@szkiba
szkiba merged commit 18a48db into main Nov 16, 2026
1 check passed
@szkiba
szkiba deleted the javadoc-1-public-api branch November 16, 2026 14:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant