apache / apache/beam

Javadoc should clearly separate facts from runner requirements

Open
#18,063 0 comments 0 reactions 0 assignees View on GitHub
bug core java P3
Dominant language
Java
Stars
8.7k
Forks
4.7k
Avg merge
2d 2h
Merged PRs (30d)
205

Description

The javadoc for View.asMap() says the map needs to fit in memory. That's not true in all runners. (For example, Dataflow has distributed map support.)

https://github.com/apache/incubator-beam/blob/master/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/View.java

This is likely just one specific case of a more general issue \-- different runners will have common constraints on the scalability of portions of the model. Currently these are documented in the capability matrix on the website, but for usability we should consider surfacing these constraints on particularly relevant methods. But keeping things in sync in multiple locations is hard...

Imported from Jira [BEAM-728](https://issues.apache.org/jira/browse/BEAM-728). Original Jira may contain additional context.
Reported by: frances.

Contributor guide

Open the contributing guide

Research direction

Start in sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/View.java and read the Javadoc for View.asMap(). Compare its memory requirement wording with the runner capability matrix referenced in the issue. Done means the documentation distinguishes model facts from runner-specific constraints and establishes how any surfaced constraints should stay consistent.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.