[jira] [Commented] (FLINK-8743) Add annotation to override documented default

[ASF GitHub Bot (JIRA)]

[ 
https://issues.apache.org/jira/browse/FLINK-8743?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16461014#comment-16461014
 ] 

ASF GitHub Bot commented on FLINK-8743:
---

Github user asfgit closed the pull request at:

https://github.com/apache/flink/pull/5822


> Add annotation to override documented default
> -
>
> Key: FLINK-8743
> URL: https://issues.apache.org/jira/browse/FLINK-8743
> Project: Flink
>  Issue Type: New Feature
>  Components: Configuration, Documentation
>Reporter: Chesnay Schepler
>Assignee: Chesnay Schepler
>Priority: Trivial
> Fix For: 1.5.0
>
>
> The default value for some {{ConfigOptions}} is difficult to document as it 
> isn't static. This mostly affects options that use 
> {{System.getProperty("java.io.tmpdir")}}, as for example 
> {{CoreOptions#TMP_DIRS}}.
> To deal with this the generator has a special branch for selected options 
> that overrides this default: 
> {code}
> if (option == WebOptions.TMP_DIR || option.key().equals("python.dc.tmp.dir") 
> || option == CoreOptions.TMP_DIRS) {
>   defaultValue = null;
> }
> {code}
> (let's ignore for now that it just wipes the default and isn't setting it to 
> "System.getProperty("java.io.tmpdir")")
> This is pretty much hidden deep in the implementation of the generator. It 
> would be better if we had a dedicated annotation 
> {{@OverrideDocumentedDefault(String override)}} that options could be 
> annotated with.



--
This message was sent by Atlassian JIRA
(v7.6.3#76005)

[jira] [Commented] (FLINK-8743) Add annotation to override documented default

[ASF GitHub Bot (JIRA)]

[ 
https://issues.apache.org/jira/browse/FLINK-8743?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16460668#comment-16460668
 ] 

ASF GitHub Bot commented on FLINK-8743:
---

Github user zentol commented on the issue:

https://github.com/apache/flink/pull/5822
  
merging.


> Add annotation to override documented default
> -
>
> Key: FLINK-8743
> URL: https://issues.apache.org/jira/browse/FLINK-8743
> Project: Flink
>  Issue Type: New Feature
>  Components: Configuration, Documentation
>Reporter: Chesnay Schepler
>Assignee: Chesnay Schepler
>Priority: Trivial
> Fix For: 1.5.0
>
>
> The default value for some {{ConfigOptions}} is difficult to document as it 
> isn't static. This mostly affects options that use 
> {{System.getProperty("java.io.tmpdir")}}, as for example 
> {{CoreOptions#TMP_DIRS}}.
> To deal with this the generator has a special branch for selected options 
> that overrides this default: 
> {code}
> if (option == WebOptions.TMP_DIR || option.key().equals("python.dc.tmp.dir") 
> || option == CoreOptions.TMP_DIRS) {
>   defaultValue = null;
> }
> {code}
> (let's ignore for now that it just wipes the default and isn't setting it to 
> "System.getProperty("java.io.tmpdir")")
> This is pretty much hidden deep in the implementation of the generator. It 
> would be better if we had a dedicated annotation 
> {{@OverrideDocumentedDefault(String override)}} that options could be 
> annotated with.



--
This message was sent by Atlassian JIRA
(v7.6.3#76005)

[jira] [Commented] (FLINK-8743) Add annotation to override documented default

[ASF GitHub Bot (JIRA)]

[ 
https://issues.apache.org/jira/browse/FLINK-8743?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16458446#comment-16458446
 ] 

ASF GitHub Bot commented on FLINK-8743:
---

Github user aljoscha commented on the issue:

https://github.com/apache/flink/pull/5822
  
Ok, makes sense to merge then.


> Add annotation to override documented default
> -
>
> Key: FLINK-8743
> URL: https://issues.apache.org/jira/browse/FLINK-8743
> Project: Flink
>  Issue Type: New Feature
>  Components: Configuration, Documentation
>Reporter: Chesnay Schepler
>Assignee: Chesnay Schepler
>Priority: Trivial
> Fix For: 1.5.0
>
>
> The default value for some {{ConfigOptions}} is difficult to document as it 
> isn't static. This mostly affects options that use 
> {{System.getProperty("java.io.tmpdir")}}, as for example 
> {{CoreOptions#TMP_DIRS}}.
> To deal with this the generator has a special branch for selected options 
> that overrides this default: 
> {code}
> if (option == WebOptions.TMP_DIR || option.key().equals("python.dc.tmp.dir") 
> || option == CoreOptions.TMP_DIRS) {
>   defaultValue = null;
> }
> {code}
> (let's ignore for now that it just wipes the default and isn't setting it to 
> "System.getProperty("java.io.tmpdir")")
> This is pretty much hidden deep in the implementation of the generator. It 
> would be better if we had a dedicated annotation 
> {{@OverrideDocumentedDefault(String override)}} that options could be 
> annotated with.



--
This message was sent by Atlassian JIRA
(v7.6.3#76005)

[jira] [Commented] (FLINK-8743) Add annotation to override documented default

[ASF GitHub Bot (JIRA)]

[ 
https://issues.apache.org/jira/browse/FLINK-8743?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16458433#comment-16458433
 ] 

ASF GitHub Bot commented on FLINK-8743:
---

Github user zentol commented on the issue:

https://github.com/apache/flink/pull/5822
  
Annotations have a number of advantages:
* they don't pollute the `ConfigOption` class with documentation concerns
* we don't have to define reasonable defaults to prevent issues at runtime
* we can add/remove annotations at any time as they aren't `@Public`


> Add annotation to override documented default
> -
>
> Key: FLINK-8743
> URL: https://issues.apache.org/jira/browse/FLINK-8743
> Project: Flink
>  Issue Type: New Feature
>  Components: Configuration, Documentation
>Reporter: Chesnay Schepler
>Assignee: Chesnay Schepler
>Priority: Trivial
> Fix For: 1.5.0
>
>
> The default value for some {{ConfigOptions}} is difficult to document as it 
> isn't static. This mostly affects options that use 
> {{System.getProperty("java.io.tmpdir")}}, as for example 
> {{CoreOptions#TMP_DIRS}}.
> To deal with this the generator has a special branch for selected options 
> that overrides this default: 
> {code}
> if (option == WebOptions.TMP_DIR || option.key().equals("python.dc.tmp.dir") 
> || option == CoreOptions.TMP_DIRS) {
>   defaultValue = null;
> }
> {code}
> (let's ignore for now that it just wipes the default and isn't setting it to 
> "System.getProperty("java.io.tmpdir")")
> This is pretty much hidden deep in the implementation of the generator. It 
> would be better if we had a dedicated annotation 
> {{@OverrideDocumentedDefault(String override)}} that options could be 
> annotated with.



--
This message was sent by Atlassian JIRA
(v7.6.3#76005)

[jira] [Commented] (FLINK-8743) Add annotation to override documented default

[ASF GitHub Bot (JIRA)]

[ 
https://issues.apache.org/jira/browse/FLINK-8743?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=16426744#comment-16426744
 ] 

ASF GitHub Bot commented on FLINK-8743:
---

GitHub user zentol opened a pull request:

https://github.com/apache/flink/pull/5822

 [FLINK-8743][docs] Allow overriding documented default 

Based on #5821.

## What is the purpose of the change

This PR adds an annotation to override the documented default.

## Verifying this change

This change added tests and can be verified as follows:

* `ConfigOptionsDocGeneratorTest#testOverrideDefault`


You can merge this pull request into a Git repository by running:

$ git pull https://github.com/zentol/flink 8743

Alternatively you can review and apply these changes as the patch at:

https://github.com/apache/flink/pull/5822.patch

To close this pull request, make a commit to your master/trunk branch
with (at least) the following in the commit message:

This closes #5822


commit 4c6527430ca5d3ac9f9c1a18cdcc403b3f47f93e
Author: zentol 
Date:   2018-04-05T10:17:27Z

[FLINK-8742][docs] Move docs generator annotations to flink-annotations

commit 10064482cc0d0e2dbddfc4d3988c4a17f78700fa
Author: zentol 
Date:   2018-04-05T10:42:42Z

[FLINK-8743][docs] Allow overriding documented default




> Add annotation to override documented default
> -
>
> Key: FLINK-8743
> URL: https://issues.apache.org/jira/browse/FLINK-8743
> Project: Flink
>  Issue Type: New Feature
>  Components: Configuration, Documentation
>Reporter: Chesnay Schepler
>Assignee: Chesnay Schepler
>Priority: Trivial
>
> The default value for some {{ConfigOptions}} is difficult to document as it 
> isn't static. This mostly affects options that use 
> {{System.getProperty("java.io.tmpdir")}}, as for example 
> {{CoreOptions#TMP_DIRS}}.
> To deal with this the generator has a special branch for selected options 
> that overrides this default: 
> {code}
> if (option == WebOptions.TMP_DIR || option.key().equals("python.dc.tmp.dir") 
> || option == CoreOptions.TMP_DIRS) {
>   defaultValue = null;
> }
> {code}
> (let's ignore for now that it just wipes the default and isn't setting it to 
> "System.getProperty("java.io.tmpdir")")
> This is pretty much hidden deep in the implementation of the generator. It 
> would be better if we had a dedicated annotation 
> {{@OverrideDocumentedDefault(String override)}} that options could be 
> annotated with.



--
This message was sent by Atlassian JIRA
(v7.6.3#76005)