Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Single-line ScalaDoc plus deprecated annotation would trigger a bug #85

Open
mengxr opened this issue Jun 22, 2016 · 1 comment
Open

Single-line ScalaDoc plus deprecated annotation would trigger a bug #85

mengxr opened this issue Jun 22, 2016 · 1 comment

Comments

@mengxr
Copy link

mengxr commented Jun 22, 2016

We recently deprecated setLabelCol in ChiSqSelectorModel in Spark (apache/spark#13823):

  /** @group setParam */
  @Since("1.6.0")
  @deprecated("labelCol is not used by ChiSqSelectorModel.", "2.0.0")
  def setLabelCol(value: String): this.type = set(labelCol, value)

This unfortunately hit a genjavadoc bug and broken doc generation. This is the generated Java code:

  /** @group setParam */
  public  org.apache.spark.ml.feature.ChiSqSelectorModel setOutputCol (java.lang.String value)  { throw new RuntimeException(); }
   *
   * @deprecated labelCol is not used by ChiSqSelectorModel. Since 2.0.0.
  */
  public  org.apache.spark.ml.feature.ChiSqSelectorModel setLabelCol (java.lang.String value)  { throw new RuntimeException(); }

Switching to multiline is a workaround (apache/spark#13855). It would be nice to fix this bug in genjavadoc.
@patriknw
Copy link
Contributor

Same here, but that is not single line:
https://github.com/akka/akka/blob/master/akka-remote/src/main/scala/akka/remote/AddressUidExtension.scala#L43

This was with Scala 2.12.0-RC2

asfgit pushed a commit to apache/spark that referenced this issue Nov 29, 2016
@HyukjinKwon @srowen
[SPARK-18615][DOCS] Switch to multi-line doc to avoid a genjavadoc bu…
1a87009 
…g for backticks

## What changes were proposed in this pull request?

Currently, single line comment does not mark down backticks to `<code>..</code>` but prints as they are (`` `..` ``). For example, the line below:

```scala
/** Return an RDD with the pairs from `this` whose keys are not in `other`. */
```

So, we could work around this as below:

```scala
/**
 * Return an RDD with the pairs from `this` whose keys are not in `other`.
 */
```

- javadoc

  - **Before**
    ![2016-11-29 10 39 14](https://cloud.githubusercontent.com/assets/6477701/20693606/e64c8f90-b622-11e6-8dfc-4a029216e23d.png)

  - **After**
    ![2016-11-29 10 39 08](https://cloud.githubusercontent.com/assets/6477701/20693607/e7280d36-b622-11e6-8502-d2e21cd5556b.png)

- scaladoc (this one looks fine either way)

  - **Before**
    ![2016-11-29 10 38 22](https://cloud.githubusercontent.com/assets/6477701/20693640/12c18aa8-b623-11e6-901a-693e2f6f8066.png)

  - **After**
    ![2016-11-29 10 40 05](https://cloud.githubusercontent.com/assets/6477701/20693642/14eb043a-b623-11e6-82ac-7cd0000106d1.png)

I suspect this is related with SPARK-16153 and genjavadoc issue in ` lightbend/genjavadoc#85`.

## How was this patch tested?

I found them via

```
grep -r "\/\*\*.*\`" . | grep .scala
````

and then checked if each is in the public API documentation with manually built docs (`jekyll build`) with Java 7.

Author: hyukjinkwon <[email protected]>

Closes #16050 from HyukjinKwon/javadoc-markdown.
asfgit pushed a commit to apache/spark that referenced this issue Nov 29, 2016
@HyukjinKwon @srowen
[SPARK-18615][DOCS] Switch to multi-line doc to avoid a genjavadoc bu…
086a3bd 
…g for backticks

## What changes were proposed in this pull request?

Currently, single line comment does not mark down backticks to `<code>..</code>` but prints as they are (`` `..` ``). For example, the line below:

```scala
/** Return an RDD with the pairs from `this` whose keys are not in `other`. */
```

So, we could work around this as below:

```scala
/**
 * Return an RDD with the pairs from `this` whose keys are not in `other`.
 */
```

- javadoc

  - **Before**
    ![2016-11-29 10 39 14](https://cloud.githubusercontent.com/assets/6477701/20693606/e64c8f90-b622-11e6-8dfc-4a029216e23d.png)

  - **After**
    ![2016-11-29 10 39 08](https://cloud.githubusercontent.com/assets/6477701/20693607/e7280d36-b622-11e6-8502-d2e21cd5556b.png)

- scaladoc (this one looks fine either way)

  - **Before**
    ![2016-11-29 10 38 22](https://cloud.githubusercontent.com/assets/6477701/20693640/12c18aa8-b623-11e6-901a-693e2f6f8066.png)

  - **After**
    ![2016-11-29 10 40 05](https://cloud.githubusercontent.com/assets/6477701/20693642/14eb043a-b623-11e6-82ac-7cd0000106d1.png)

I suspect this is related with SPARK-16153 and genjavadoc issue in ` lightbend/genjavadoc#85`.

## How was this patch tested?

I found them via

```
grep -r "\/\*\*.*\`" . | grep .scala
````

and then checked if each is in the public API documentation with manually built docs (`jekyll build`) with Java 7.

Author: hyukjinkwon <[email protected]>

Closes #16050 from HyukjinKwon/javadoc-markdown.

(cherry picked from commit 1a87009)
Signed-off-by: Sean Owen <[email protected]>
robert3005 pushed a commit to palantir/spark that referenced this issue Dec 2, 2016
@HyukjinKwon
[SPARK-18615][DOCS] Switch to multi-line doc to avoid a genjavadoc bu…
470c3c8 
…g for backticks

## What changes were proposed in this pull request?

Currently, single line comment does not mark down backticks to `<code>..</code>` but prints as they are (`` `..` ``). For example, the line below:

```scala
/** Return an RDD with the pairs from `this` whose keys are not in `other`. */
```

So, we could work around this as below:

```scala
/**
 * Return an RDD with the pairs from `this` whose keys are not in `other`.
 */
```

- javadoc

  - **Before**
    ![2016-11-29 10 39 14](https://cloud.githubusercontent.com/assets/6477701/20693606/e64c8f90-b622-11e6-8dfc-4a029216e23d.png)

  - **After**
    ![2016-11-29 10 39 08](https://cloud.githubusercontent.com/assets/6477701/20693607/e7280d36-b622-11e6-8502-d2e21cd5556b.png)

- scaladoc (this one looks fine either way)

  - **Before**
    ![2016-11-29 10 38 22](https://cloud.githubusercontent.com/assets/6477701/20693640/12c18aa8-b623-11e6-901a-693e2f6f8066.png)

  - **After**
    ![2016-11-29 10 40 05](https://cloud.githubusercontent.com/assets/6477701/20693642/14eb043a-b623-11e6-82ac-7cd0000106d1.png)

I suspect this is related with SPARK-16153 and genjavadoc issue in ` lightbend/genjavadoc#85`.

## How was this patch tested?

I found them via

```
grep -r "\/\*\*.*\`" . | grep .scala
````

and then checked if each is in the public API documentation with manually built docs (`jekyll build`) with Java 7.

Author: hyukjinkwon <[email protected]>

Closes apache#16050 from HyukjinKwon/javadoc-markdown.
uzadude pushed a commit to uzadude/spark that referenced this issue Jan 27, 2017
@HyukjinKwon @uzadude
[SPARK-18615][DOCS] Switch to multi-line doc to avoid a genjavadoc bu…
2292bd9 
…g for backticks

## What changes were proposed in this pull request?

Currently, single line comment does not mark down backticks to `<code>..</code>` but prints as they are (`` `..` ``). For example, the line below:

```scala
/** Return an RDD with the pairs from `this` whose keys are not in `other`. */
```

So, we could work around this as below:

```scala
/**
 * Return an RDD with the pairs from `this` whose keys are not in `other`.
 */
```

- javadoc

  - **Before**
    ![2016-11-29 10 39 14](https://cloud.githubusercontent.com/assets/6477701/20693606/e64c8f90-b622-11e6-8dfc-4a029216e23d.png)

  - **After**
    ![2016-11-29 10 39 08](https://cloud.githubusercontent.com/assets/6477701/20693607/e7280d36-b622-11e6-8502-d2e21cd5556b.png)

- scaladoc (this one looks fine either way)

  - **Before**
    ![2016-11-29 10 38 22](https://cloud.githubusercontent.com/assets/6477701/20693640/12c18aa8-b623-11e6-901a-693e2f6f8066.png)

  - **After**
    ![2016-11-29 10 40 05](https://cloud.githubusercontent.com/assets/6477701/20693642/14eb043a-b623-11e6-82ac-7cd0000106d1.png)

I suspect this is related with SPARK-16153 and genjavadoc issue in ` lightbend/genjavadoc#85`.

## How was this patch tested?

I found them via

```
grep -r "\/\*\*.*\`" . | grep .scala
````

and then checked if each is in the public API documentation with manually built docs (`jekyll build`) with Java 7.

Author: hyukjinkwon <[email protected]>

Closes apache#16050 from HyukjinKwon/javadoc-markdown.
@johanandren johanandren mentioned this issue Aug 3, 2017
Merged
jrudolph added a commit to jrudolph/genjavadoc that referenced this issue Sep 18, 2017
@jrudolph
Don't fail for deprecated lazy vals, fixes lightbend#85.
d898589 
This somewhat fixes lightbend#85 so that genjavadoc does at least not fail. However,
like in the case for deprecated lazy vals with preexisting scaladoc, the
preexisting comment might be lost under some Scala versions.

The reason seems to be that starting from Scala 2.12 positions are reported
in a way that puts the original position on the private `$lzycompute` method
instead of on the accessor. To fix that additional considerations are necessary
to somehow reconcile position information from the lzycompute with the actual
accessor so that existing and generated scaladoc can be merged.
@jrudolph jrudolph mentioned this issue Sep 18, 2017
Closed
jrudolph added a commit to jrudolph/akka that referenced this issue Sep 19, 2017
@jrudolph
=str hide deprecated lazy vals behind def in FanInShape
93dca5c 
To avoid genjavadoc issue lightbend/genjavadoc#85.
jrudolph added a commit to jrudolph/akka that referenced this issue Sep 19, 2017
@jrudolph
=str hide deprecated lazy vals behind def in FanInShape et al
7352a96 
To avoid genjavadoc issue lightbend/genjavadoc#85.
@jrudolph jrudolph mentioned this issue Sep 19, 2017
Merged
raboof pushed a commit to akka/akka that referenced this issue Sep 19, 2017
@jrudolph @raboof
=str hide deprecated lazy vals behind def in FanInShape et al (#23655)
3307b35 
To avoid genjavadoc issue lightbend/genjavadoc#85.
lucianenache pushed a commit to lucianenache/akka that referenced this issue Nov 6, 2017
@jrudolph
=str hide deprecated lazy vals behind def in FanInShape et al (akka#2…
09c1f58 
…3655)

To avoid genjavadoc issue lightbend/genjavadoc#85.
lucianenache pushed a commit to lucianenache/akka that referenced this issue Nov 9, 2017
@jrudolph
=str hide deprecated lazy vals behind def in FanInShape et al (akka#2…
8f3afa6 
…3655)

To avoid genjavadoc issue lightbend/genjavadoc#85.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Don't fail for deprecated lazy vals, fixes #85. jrudolph/genjavadoc
2 participants
@patriknw @mengxr