You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@daffodil.apache.org by GitBox <gi...@apache.org> on 2020/07/14 14:32:46 UTC
[GitHub] [incubator-daffodil] stevedlawrence opened a new pull request #397: Use sbt-unidoc plugin for generating public API documentation
stevedlawrence opened a new pull request #397:
URL: https://github.com/apache/incubator-daffodil/pull/397
Rather than running Javadoc/Scaladoc commands separately to build our
public API documentation, we can now just run "sbt unidoc". That
generates both Java and Scala documentation in the root target
directory, including docs combined from the japi, sapi, and udf
subprojects. This also allows for easily adding new public API
documentation for other features, such as planned DSOM walker, by just
creating a new subproject and adding it to the unidocProjectFilter sbt
setting.
DAFFODIL-2368
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-daffodil] stevedlawrence closed pull request #397: Use sbt-unidoc plugin for generating public API documentation
Posted by GitBox <gi...@apache.org>.
stevedlawrence closed pull request #397:
URL: https://github.com/apache/incubator-daffodil/pull/397
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-daffodil] stevedlawrence commented on pull request #397: Use sbt-unidoc plugin for generating public API documentation
Posted by GitBox <gi...@apache.org>.
stevedlawrence commented on pull request #397:
URL: https://github.com/apache/incubator-daffodil/pull/397#issuecomment-658820715
The daffodil-japi subproject is written in scala, but we want to generate javadocs for, since the intended usage is with Java code. There is a scala compiler plugin called [genjavadoc](https://github.com/lightbend/genjavadoc) that will generate javadocs from scala source files. You don't actually need to use the unidoc plugin to get this feature. The latest version of this scalac compiler plugin is 0.16.
The sbt-unidoc plugin essentially just takes java/scaladocs from subprojects and combines them into one big java/scaladoc. The 0.4.3 is the version of the sbt-unidoc plugin. Note that sbt-unidoc also acts as a wrapper around genjavadoc, so you gen generate javadocs for a subproject using the scala compiler plugin, and then sbt-unidoc will pull those in when it combines everything.
So in short, one version is for the sbt-unidoc plugin, the other is for the genjavadoc plugin that it wraps.
I originally did a visual inspection and things looked the same. To confirm, I just ran a diff to see what the actual changes were:
1. Javadoc includes a generation timestamp. I'm thinking it make sense to include the {{-notimestamp}} option when generating docs so we don't get a 1000 line diff of just timestamps.
2. The order of two rows in a deprecation table are randomly flipped. No idea why this happened, but it doesn't really matter I guess.
3. I modified the root-doc.txt file, which is apparently included in many scaladoc files as a tooltip. This diff is expected, but the tooltip should be something different instead of the entire contents of that file. I'll see if that's easy to fix.
4. The UDF API additions, which is also expected.
So all diffs are expected. I think it's worth ammending this PR to disable timestamps and fix the tooltip.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [incubator-daffodil] stevedlawrence commented on pull request #397: Use sbt-unidoc plugin for generating public API documentation
Posted by GitBox <gi...@apache.org>.
stevedlawrence commented on pull request #397:
URL: https://github.com/apache/incubator-daffodil/pull/397#issuecomment-658839830
Github isn't updating this PR with new commits to the branch. I'm going to close and create a new PR and see if that works.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org