Hi,
I helped somebody yesterday on SO [1] who had issues with the Scala API because he was importing the classes from the Java API. Somebody else complained about this issue as well in the comments below the documentation [2], and I think both users are right: Its an unnecessary obstacle when learning Flink that users have to figure out which class to import. How about adding import statements to the examples? Is there a nicer way of solving the problem? Regards, Robert [1] http://stackoverflow.com/a/33721528/568695 [2]: https://ci.apache.org/projects/flink/flink-docs-release-0.10/apis/streaming_guide.html#comment-2365998014 |
I agree that it would be nice to be able to simply copy paste examples from
Flink's website. But it would also be nice if one could hide the imports because they usually take a lot of space. Cheers, Till On Wed, Nov 18, 2015 at 12:09 PM, Robert Metzger <[hidden email]> wrote: > Hi, > > I helped somebody yesterday on SO [1] who had issues with the Scala API > because he was importing the classes from the Java API. > Somebody else complained about this issue as well in the comments below the > documentation [2], and I think both users are right: Its an unnecessary > obstacle when learning Flink that users have to figure out which class to > import. > > How about adding import statements to the examples? > Is there a nicer way of solving the problem? > > > Regards, > Robert > > > > [1] http://stackoverflow.com/a/33721528/568695 > [2]: > > https://ci.apache.org/projects/flink/flink-docs-release-0.10/apis/streaming_guide.html#comment-2365998014 > |
In reply to this post by Robert Metzger
Hi Robert.
Good suggestion. Generally, it would be nice to have complete code examples available in the documentation. Even better, a way to only show excerpts of the complete example with the option of copying the complete working example. For instance: public Example { public static void main(String[] args) { ExecutionEnvironment env = ... // BEGIN: example env.fromElements(1,2,3,4) env.map(element -> element * 2) // END: example env.print(); } } This still poses the problem that we need to run those examples in an automated way to ensure they are actually working. Cheers, Max On Wed, Nov 18, 2015 at 12:09 PM, Robert Metzger <[hidden email]> wrote: > Hi, > > I helped somebody yesterday on SO [1] who had issues with the Scala API > because he was importing the classes from the Java API. > Somebody else complained about this issue as well in the comments below the > documentation [2], and I think both users are right: Its an unnecessary > obstacle when learning Flink that users have to figure out which class to > import. > > How about adding import statements to the examples? > Is there a nicer way of solving the problem? > > > Regards, > Robert > > > > [1] http://stackoverflow.com/a/33721528/568695 > [2]: > https://ci.apache.org/projects/flink/flink-docs-release-0.10/apis/streaming_guide.html#comment-2365998014 |
In HBase we keep an hbase-examples module with working code. Snippets from
that module are pasted into docs and referenced. Yes, we do see divergence, especially when refactor tools are involved. I once looked into a doc tool for automatically extracting snippets from source code, but that turned into a rat-hole and didn't pursue it further. Maybe tooling has improved since then? On Wednesday, November 18, 2015, Maximilian Michels <[hidden email]> wrote: > Hi Robert. > > Good suggestion. Generally, it would be nice to have complete code > examples available in the documentation. Even better, a way to only > show excerpts of the complete example with the option of copying the > complete working example. > > For instance: > > public Example { > public static void main(String[] args) { > ExecutionEnvironment env = ... > > // BEGIN: example > env.fromElements(1,2,3,4) > env.map(element -> element * 2) > // END: example > > env.print(); > } > } > > This still poses the problem that we need to run those examples in an > automated way to ensure they are actually working. > > Cheers, > Max > > On Wed, Nov 18, 2015 at 12:09 PM, Robert Metzger <[hidden email] > <javascript:;>> wrote: > > Hi, > > > > I helped somebody yesterday on SO [1] who had issues with the Scala API > > because he was importing the classes from the Java API. > > Somebody else complained about this issue as well in the comments below > the > > documentation [2], and I think both users are right: Its an unnecessary > > obstacle when learning Flink that users have to figure out which class to > > import. > > > > How about adding import statements to the examples? > > Is there a nicer way of solving the problem? > > > > > > Regards, > > Robert > > > > > > > > [1] http://stackoverflow.com/a/33721528/568695 > > [2]: > > > https://ci.apache.org/projects/flink/flink-docs-release-0.10/apis/streaming_guide.html#comment-2365998014 > |
Thank you for the feedback.
I was also spending some time thinking about automating this, but I don't have the time right now to bring the required infrastructure in place. For now, I'll just add import statements for classes with the potential of confusion (in particular between the Scala and Java API, Hadoop/Flink classes, ..) Also, I'll not add the import statements to ALL examples, only to those where people might copy paste them. Please -1 me if you are against this, otherwise, I'll soon open a PR. On Wed, Nov 18, 2015 at 5:04 PM, Nick Dimiduk <[hidden email]> wrote: > In HBase we keep an hbase-examples module with working code. Snippets from > that module are pasted into docs and referenced. Yes, we do see divergence, > especially when refactor tools are involved. I once looked into a doc tool > for automatically extracting snippets from source code, but that turned > into a rat-hole and didn't pursue it further. Maybe tooling has improved > since then? > > On Wednesday, November 18, 2015, Maximilian Michels <[hidden email]> > wrote: > > > Hi Robert. > > > > Good suggestion. Generally, it would be nice to have complete code > > examples available in the documentation. Even better, a way to only > > show excerpts of the complete example with the option of copying the > > complete working example. > > > > For instance: > > > > public Example { > > public static void main(String[] args) { > > ExecutionEnvironment env = ... > > > > // BEGIN: example > > env.fromElements(1,2,3,4) > > env.map(element -> element * 2) > > // END: example > > > > env.print(); > > } > > } > > > > This still poses the problem that we need to run those examples in an > > automated way to ensure they are actually working. > > > > Cheers, > > Max > > > > On Wed, Nov 18, 2015 at 12:09 PM, Robert Metzger <[hidden email] > > <javascript:;>> wrote: > > > Hi, > > > > > > I helped somebody yesterday on SO [1] who had issues with the Scala API > > > because he was importing the classes from the Java API. > > > Somebody else complained about this issue as well in the comments below > > the > > > documentation [2], and I think both users are right: Its an unnecessary > > > obstacle when learning Flink that users have to figure out which class > to > > > import. > > > > > > How about adding import statements to the examples? > > > Is there a nicer way of solving the problem? > > > > > > > > > Regards, > > > Robert > > > > > > > > > > > > [1] http://stackoverflow.com/a/33721528/568695 > > > [2]: > > > > > > https://ci.apache.org/projects/flink/flink-docs-release-0.10/apis/streaming_guide.html#comment-2365998014 > > > |
I think it's confusing to only have a subset of import statements provided.
But then again, the missing ones will be resolved without confusion (hopefully) ;) We can go with this and see what feedback we get. (Just doing it for some examples sounds reasonable.) – Ufuk On Thu, Nov 19, 2015 at 5:29 PM, Robert Metzger <[hidden email]> wrote: > Thank you for the feedback. > > I was also spending some time thinking about automating this, but I don't > have the time right now to bring the required infrastructure in place. > > For now, I'll just add import statements for classes with the potential of > confusion (in particular between the Scala and Java API, Hadoop/Flink > classes, ..) > Also, I'll not add the import statements to ALL examples, only to those > where people might copy paste them. > Please -1 me if you are against this, otherwise, I'll soon open a PR. > > > On Wed, Nov 18, 2015 at 5:04 PM, Nick Dimiduk <[hidden email]> wrote: > > > In HBase we keep an hbase-examples module with working code. Snippets > from > > that module are pasted into docs and referenced. Yes, we do see > divergence, > > especially when refactor tools are involved. I once looked into a doc > tool > > for automatically extracting snippets from source code, but that turned > > into a rat-hole and didn't pursue it further. Maybe tooling has improved > > since then? > > > > On Wednesday, November 18, 2015, Maximilian Michels <[hidden email]> > > wrote: > > > > > Hi Robert. > > > > > > Good suggestion. Generally, it would be nice to have complete code > > > examples available in the documentation. Even better, a way to only > > > show excerpts of the complete example with the option of copying the > > > complete working example. > > > > > > For instance: > > > > > > public Example { > > > public static void main(String[] args) { > > > ExecutionEnvironment env = ... > > > > > > // BEGIN: example > > > env.fromElements(1,2,3,4) > > > env.map(element -> element * 2) > > > // END: example > > > > > > env.print(); > > > } > > > } > > > > > > This still poses the problem that we need to run those examples in an > > > automated way to ensure they are actually working. > > > > > > Cheers, > > > Max > > > > > > On Wed, Nov 18, 2015 at 12:09 PM, Robert Metzger <[hidden email] > > > <javascript:;>> wrote: > > > > Hi, > > > > > > > > I helped somebody yesterday on SO [1] who had issues with the Scala > API > > > > because he was importing the classes from the Java API. > > > > Somebody else complained about this issue as well in the comments > below > > > the > > > > documentation [2], and I think both users are right: Its an > unnecessary > > > > obstacle when learning Flink that users have to figure out which > class > > to > > > > import. > > > > > > > > How about adding import statements to the examples? > > > > Is there a nicer way of solving the problem? > > > > > > > > > > > > Regards, > > > > Robert > > > > > > > > > > > > > > > > [1] http://stackoverflow.com/a/33721528/568695 > > > > [2]: > > > > > > > > > > https://ci.apache.org/projects/flink/flink-docs-release-0.10/apis/streaming_guide.html#comment-2365998014 > > > > > > |
>Also, I'll not add the import statements to ALL examples, only to those
>where people might copy paste them. That sounds ok to me for now. On Thu, Nov 19, 2015 at 6:38 PM, Ufuk Celebi <[hidden email]> wrote: > I think it's confusing to only have a subset of import statements provided. > But then again, the missing ones will be resolved without confusion > (hopefully) ;) We can go with this and see what feedback we get. > > (Just doing it for some examples sounds reasonable.) > > – Ufuk > > On Thu, Nov 19, 2015 at 5:29 PM, Robert Metzger <[hidden email]> wrote: > >> Thank you for the feedback. >> >> I was also spending some time thinking about automating this, but I don't >> have the time right now to bring the required infrastructure in place. >> >> For now, I'll just add import statements for classes with the potential of >> confusion (in particular between the Scala and Java API, Hadoop/Flink >> classes, ..) >> Also, I'll not add the import statements to ALL examples, only to those >> where people might copy paste them. >> Please -1 me if you are against this, otherwise, I'll soon open a PR. >> >> >> On Wed, Nov 18, 2015 at 5:04 PM, Nick Dimiduk <[hidden email]> wrote: >> >> > In HBase we keep an hbase-examples module with working code. Snippets >> from >> > that module are pasted into docs and referenced. Yes, we do see >> divergence, >> > especially when refactor tools are involved. I once looked into a doc >> tool >> > for automatically extracting snippets from source code, but that turned >> > into a rat-hole and didn't pursue it further. Maybe tooling has improved >> > since then? >> > >> > On Wednesday, November 18, 2015, Maximilian Michels <[hidden email]> >> > wrote: >> > >> > > Hi Robert. >> > > >> > > Good suggestion. Generally, it would be nice to have complete code >> > > examples available in the documentation. Even better, a way to only >> > > show excerpts of the complete example with the option of copying the >> > > complete working example. >> > > >> > > For instance: >> > > >> > > public Example { >> > > public static void main(String[] args) { >> > > ExecutionEnvironment env = ... >> > > >> > > // BEGIN: example >> > > env.fromElements(1,2,3,4) >> > > env.map(element -> element * 2) >> > > // END: example >> > > >> > > env.print(); >> > > } >> > > } >> > > >> > > This still poses the problem that we need to run those examples in an >> > > automated way to ensure they are actually working. >> > > >> > > Cheers, >> > > Max >> > > >> > > On Wed, Nov 18, 2015 at 12:09 PM, Robert Metzger <[hidden email] >> > > <javascript:;>> wrote: >> > > > Hi, >> > > > >> > > > I helped somebody yesterday on SO [1] who had issues with the Scala >> API >> > > > because he was importing the classes from the Java API. >> > > > Somebody else complained about this issue as well in the comments >> below >> > > the >> > > > documentation [2], and I think both users are right: Its an >> unnecessary >> > > > obstacle when learning Flink that users have to figure out which >> class >> > to >> > > > import. >> > > > >> > > > How about adding import statements to the examples? >> > > > Is there a nicer way of solving the problem? >> > > > >> > > > >> > > > Regards, >> > > > Robert >> > > > >> > > > >> > > > >> > > > [1] http://stackoverflow.com/a/33721528/568695 >> > > > [2]: >> > > > >> > > >> > >> https://ci.apache.org/projects/flink/flink-docs-release-0.10/apis/streaming_guide.html#comment-2365998014 >> > > >> > >> |
Free forum by Nabble | Edit this page |