[jira] Created: (MATH-445) Replace "package.html" by "package-info.java"

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

[jira] Created: (MATH-445) Replace "package.html" by "package-info.java"

ASF GitHub Bot (Jira)
Replace "package.html" by "package-info.java"
---------------------------------------------

                 Key: MATH-445
                 URL: https://issues.apache.org/jira/browse/MATH-445
             Project: Commons Math
          Issue Type: Task
            Reporter: Gilles
            Priority: Trivial
             Fix For: 3.0


The newest (and recommended, I think) way of documenting packages is through "package-info.java" files.
CM still uses "package.html" files.


--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.

Reply | Threaded
Open this post in threaded view
|

[jira] [Commented] (MATH-445) Replace "package.html" by "package-info.java"

ASF GitHub Bot (Jira)

    [ https://issues.apache.org/jira/browse/MATH-445?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13044507#comment-13044507 ]

Luc Maisonobe commented on MATH-445:
------------------------------------

I'm not sure there is any gain for this.
As far as I understand, package-info.java allo to put annotations at package level, which we don't use at all.
So it someone has a way to deal with this automatically (using some sed/perl/whatever script), then why not, but if we have to change everything manually, it would be a pain.

> Replace "package.html" by "package-info.java"
> ---------------------------------------------
>
>                 Key: MATH-445
>                 URL: https://issues.apache.org/jira/browse/MATH-445
>             Project: Commons Math
>          Issue Type: Task
>            Reporter: Gilles
>            Priority: Trivial
>             Fix For: 3.0
>
>
> The newest (and recommended, I think) way of documenting packages is through "package-info.java" files.
> CM still uses "package.html" files.

--
This message is automatically generated by JIRA.
For more information on JIRA, see: http://www.atlassian.com/software/jira
Reply | Threaded
Open this post in threaded view
|

[jira] [Commented] (MATH-445) Replace "package.html" by "package-info.java"

ASF GitHub Bot (Jira)
In reply to this post by ASF GitHub Bot (Jira)

    [ https://issues.apache.org/jira/browse/MATH-445?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13068353#comment-13068353 ]

Luc Maisonobe commented on MATH-445:
------------------------------------

As per my previous comment, I would suggest to set this issue as WONT'FIX.

What do other people think about this ?

> Replace "package.html" by "package-info.java"
> ---------------------------------------------
>
>                 Key: MATH-445
>                 URL: https://issues.apache.org/jira/browse/MATH-445
>             Project: Commons Math
>          Issue Type: Task
>            Reporter: Gilles
>            Priority: Trivial
>             Fix For: 3.0
>
>
> The newest (and recommended, I think) way of documenting packages is through "package-info.java" files.
> CM still uses "package.html" files.

--
This message is automatically generated by JIRA.
For more information on JIRA, see: http://www.atlassian.com/software/jira

       
Reply | Threaded
Open this post in threaded view
|

[jira] [Commented] (MATH-445) Replace "package.html" by "package-info.java"

ASF GitHub Bot (Jira)
In reply to this post by ASF GitHub Bot (Jira)

    [ https://issues.apache.org/jira/browse/MATH-445?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13068371#comment-13068371 ]

Gilles commented on MATH-445:
-----------------------------

It doesn't hurt to leave it open. Maybe someone will come up with the hoped-for script.


> Replace "package.html" by "package-info.java"
> ---------------------------------------------
>
>                 Key: MATH-445
>                 URL: https://issues.apache.org/jira/browse/MATH-445
>             Project: Commons Math
>          Issue Type: Task
>            Reporter: Gilles
>            Priority: Trivial
>             Fix For: 3.0
>
>
> The newest (and recommended, I think) way of documenting packages is through "package-info.java" files.
> CM still uses "package.html" files.

--
This message is automatically generated by JIRA.
For more information on JIRA, see: http://www.atlassian.com/software/jira

       
Reply | Threaded
Open this post in threaded view
|

[jira] [Commented] (MATH-445) Replace "package.html" by "package-info.java"

ASF GitHub Bot (Jira)
In reply to this post by ASF GitHub Bot (Jira)

    [ https://issues.apache.org/jira/browse/MATH-445?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13071482#comment-13071482 ]

Henri Yandell commented on MATH-445:
------------------------------------

I'm happy to volunteer for such a script; but I'm not sure there's any point having package-info.java if you don't plan to have package level annotations.

> Replace "package.html" by "package-info.java"
> ---------------------------------------------
>
>                 Key: MATH-445
>                 URL: https://issues.apache.org/jira/browse/MATH-445
>             Project: Commons Math
>          Issue Type: Task
>            Reporter: Gilles
>            Priority: Trivial
>             Fix For: 3.0
>
>
> The newest (and recommended, I think) way of documenting packages is through "package-info.java" files.
> CM still uses "package.html" files.

--
This message is automatically generated by JIRA.
For more information on JIRA, see: http://www.atlassian.com/software/jira

       
Reply | Threaded
Open this post in threaded view
|

[jira] [Commented] (MATH-445) Replace "package.html" by "package-info.java"

ASF GitHub Bot (Jira)
In reply to this post by ASF GitHub Bot (Jira)

    [ https://issues.apache.org/jira/browse/MATH-445?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13072118#comment-13072118 ]

Gilles commented on MATH-445:
-----------------------------

If you can provide such a script, there is no point in keeping the old format.


> Replace "package.html" by "package-info.java"
> ---------------------------------------------
>
>                 Key: MATH-445
>                 URL: https://issues.apache.org/jira/browse/MATH-445
>             Project: Commons Math
>          Issue Type: Task
>            Reporter: Gilles
>            Priority: Trivial
>             Fix For: 3.0
>
>
> The newest (and recommended, I think) way of documenting packages is through "package-info.java" files.
> CM still uses "package.html" files.

--
This message is automatically generated by JIRA.
For more information on JIRA, see: http://www.atlassian.com/software/jira

       
Reply | Threaded
Open this post in threaded view
|

[jira] [Resolved] (MATH-445) Replace "package.html" by "package-info.java"

ASF GitHub Bot (Jira)
In reply to this post by ASF GitHub Bot (Jira)

     [ https://issues.apache.org/jira/browse/MATH-445?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Luc Maisonobe resolved MATH-445.
--------------------------------

    Resolution: Fixed

Fixed in subversion repository as of r1178067.

A shell+sed script has been created for this conversion, it can be found here: [http://people.apache.org/~luc/convert-to-package-info.sh]
               

> Replace "package.html" by "package-info.java"
> ---------------------------------------------
>
>                 Key: MATH-445
>                 URL: https://issues.apache.org/jira/browse/MATH-445
>             Project: Commons Math
>          Issue Type: Task
>            Reporter: Gilles
>            Priority: Trivial
>             Fix For: 3.0
>
>
> The newest (and recommended, I think) way of documenting packages is through "package-info.java" files.
> CM still uses "package.html" files.

--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators: https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira

       
Reply | Threaded
Open this post in threaded view
|

[jira] [Commented] (MATH-445) Replace "package.html" by "package-info.java"

ASF GitHub Bot (Jira)
In reply to this post by ASF GitHub Bot (Jira)

    [ https://issues.apache.org/jira/browse/MATH-445?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13118901#comment-13118901 ]

Phil Steitz commented on MATH-445:
----------------------------------

Might be good to commit the script somewhere, like committers/tools for other projects that may want to do this.
               

> Replace "package.html" by "package-info.java"
> ---------------------------------------------
>
>                 Key: MATH-445
>                 URL: https://issues.apache.org/jira/browse/MATH-445
>             Project: Commons Math
>          Issue Type: Task
>            Reporter: Gilles
>            Priority: Trivial
>             Fix For: 3.0
>
>
> The newest (and recommended, I think) way of documenting packages is through "package-info.java" files.
> CM still uses "package.html" files.

--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators: https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira

       
Reply | Threaded
Open this post in threaded view
|

[jira] [Reopened] (MATH-445) Replace "package.html" by "package-info.java"

ASF GitHub Bot (Jira)
In reply to this post by ASF GitHub Bot (Jira)

     [ https://issues.apache.org/jira/browse/MATH-445?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Gilles reopened MATH-445:
-------------------------


Missing "package.html" now trigger a CheckStyle complaint.

I tried to replace the old rule with
{noformat}
  <module name="JavadocPackage"/>
{noformat}
(as documented [here|http://checkstyle.sourceforge.net/config_javadoc.html]), but this prevents the plugin to work correctly:
{noformat}
[INFO] Generating "Checkstyle" report.
[INFO] ------------------------------------------------------------------------
[ERROR] BUILD ERROR
[INFO] ------------------------------------------------------------------------
[INFO] Error during page generation

Embedded error: Error rendering Maven report: Failed during checkstyle configuration
Unable to instantiate JavadocPackageCheck
{noformat}
Maybe that the plugin version is too old (?).
               

> Replace "package.html" by "package-info.java"
> ---------------------------------------------
>
>                 Key: MATH-445
>                 URL: https://issues.apache.org/jira/browse/MATH-445
>             Project: Commons Math
>          Issue Type: Task
>            Reporter: Gilles
>            Priority: Trivial
>             Fix For: 3.0
>
>
> The newest (and recommended, I think) way of documenting packages is through "package-info.java" files.
> CM still uses "package.html" files.

--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators: https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira

       
Reply | Threaded
Open this post in threaded view
|

[jira] [Commented] (MATH-445) Replace "package.html" by "package-info.java"

ASF GitHub Bot (Jira)
In reply to this post by ASF GitHub Bot (Jira)

    [ https://issues.apache.org/jira/browse/MATH-445?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13118946#comment-13118946 ]

Gilles commented on MATH-445:
-----------------------------

Also: Isn't the script missing the generation of one space after the "*" character?

E.g.
{noformat}
/**
 *Decimal floating point library for Java
 *
{noformat}
should have been
{noformat}
/**
 * Decimal floating point library for Java
 *
{noformat}

               

> Replace "package.html" by "package-info.java"
> ---------------------------------------------
>
>                 Key: MATH-445
>                 URL: https://issues.apache.org/jira/browse/MATH-445
>             Project: Commons Math
>          Issue Type: Task
>            Reporter: Gilles
>            Priority: Trivial
>             Fix For: 3.0
>
>
> The newest (and recommended, I think) way of documenting packages is through "package-info.java" files.
> CM still uses "package.html" files.

--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators: https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira

       
Reply | Threaded
Open this post in threaded view
|

[jira] [Resolved] (MATH-445) Replace "package.html" by "package-info.java"

ASF GitHub Bot (Jira)
In reply to this post by ASF GitHub Bot (Jira)

     [ https://issues.apache.org/jira/browse/MATH-445?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Luc Maisonobe resolved MATH-445.
--------------------------------

    Resolution: Fixed

Fixed in subversion repository as of r1178168.

The script has been fixed with respect to the missing space and committed in commons/script for general use.

The missing spaces have been added directly to the already converted package-info.java files.

The checkstyle plugin used by maven has been upgraded so the underlying checkstyle is 5.x, so we can use package-info.java.
               

> Replace "package.html" by "package-info.java"
> ---------------------------------------------
>
>                 Key: MATH-445
>                 URL: https://issues.apache.org/jira/browse/MATH-445
>             Project: Commons Math
>          Issue Type: Task
>            Reporter: Gilles
>            Priority: Trivial
>             Fix For: 3.0
>
>
> The newest (and recommended, I think) way of documenting packages is through "package-info.java" files.
> CM still uses "package.html" files.

--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators: https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira