[DISCUSS] Include import statements in documentation code examples

classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|

[DISCUSS] Include import statements in documentation code examples

Robert Metzger
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
Reply | Threaded
Open this post in threaded view
|

Re: [DISCUSS] Include import statements in documentation code examples

Till Rohrmann
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
>
mxm
Reply | Threaded
Open this post in threaded view
|

Re: [DISCUSS] Include import statements in documentation code examples

mxm
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
Reply | Threaded
Open this post in threaded view
|

Re: [DISCUSS] Include import statements in documentation code examples

Nick Dimiduk
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
>
Reply | Threaded
Open this post in threaded view
|

Re: [DISCUSS] Include import statements in documentation code examples

Robert Metzger
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
> >
>
Reply | Threaded
Open this post in threaded view
|

Re: [DISCUSS] Include import statements in documentation code examples

Ufuk Celebi-2
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
> > >
> >
>
mxm
Reply | Threaded
Open this post in threaded view
|

Re: [DISCUSS] Include import statements in documentation code examples

mxm
>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
>> > >
>> >
>>