+1 A per-transform reference will definitely help Python (and Go ?) since some transforms lack detailed documentation compared to Java. Additionally it might be a good idea to compare Java/Py/Go docs in general to make sure there are no inconsistencies.
- Cham On Wed, Feb 28, 2018 at 10:53 AM Lukasz Cwik <[email protected]> wrote: > +1 > > On Wed, Feb 28, 2018 at 10:46 AM, Kenneth Knowles <[email protected]> wrote: > >> Yes! I love the idea of having a good cross-language transform reference >> on the web site. Very good idea to get started now and provide the >> skeleton, then fill out additional transforms and additional languages >> incrementally. >> >> Kenn >> >> On Wed, Feb 28, 2018 at 10:23 AM, Rafael Fernandez <[email protected]> >> wrote: >> >>> Hi folks, >>> >>> I think we've all seen a few areas of improvement here and there in our >>> docs. For example, one can find a a Javadoc entry with outdated content >>> here and there [1], or "sample" code snippets that have problems, such as >>> not compiling [2]. >>> >>> I think a good thing to do is to invest in extending our documentation >>> to having a robust per-transform reference, which has samples and a good >>> description of what the transform does, and keep JavaDoc as a solid source >>> of API documentation. I believe similar approaches can benefit Python and >>> other languages. >>> >>> What do you think? I'm happy to spend some time now and then and >>> incrementaly move in this direction. I would like some help from the >>> community with reviews, suggestions (and perhaps picking up associated >>> JIRAs as I file them.) Good idea? Bad? Try? +1? >>> >>> Thanks, >>> r >>> >>> [1] See >>> https://github.com/apache/beam/blob/a629f73ee4e64c470e0c78cc6f51b8625d781b41/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/CombineWithContext.java >>> , which contains a stale reference to KeyedCombineFn . >>> >>> [2] >>> https://github.com/apache/beam/blob/5fb30ec8265c841cd8c4e6ae16b43be1f171eabb/sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/FlatMapElements.java#L65 >>> >> >> >
