Skip to content

Commit 9f092ba

Browse files
nebhalenebhale
committed
Use Yard macros in API docs
Previously there was a hole in our API documentation that overridden methods did not inherit their parent's documentation. There is an issue open with the Yard team to fix this bug, but until then the decision was made to use Yard macros to duplicate the documentation. This change adds the Yard macros and cleans up other miscellaneous documentation errors. [#59111410]
1 parent 6f502e7 commit 9f092ba

49 files changed

Lines changed: 222 additions & 100 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎Rakefile‎

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,19 +13,35 @@
1313
# See the License for the specific language governing permissions and
1414
# limitations under the License.
1515

16+
RUBY_FILES = Dir.glob(%w(lib/*.rb
17+
lib/java_buildpack/*.rb
18+
lib/java_buildpack/component/*.rb
19+
lib/java_buildpack/container/*.rb
20+
lib/java_buildpack/framework/*.rb
21+
lib/java_buildpack/framework/spring_auto_reconfiguration/*.rb
22+
lib/java_buildpack/jre/*.rb
23+
lib/java_buildpack/jre/memory/*.rb
24+
lib/java_buildpack/logging/*.rb
25+
lib/java_buildpack/repository/*.rb
26+
lib/java_buildpack/util/*.rb
27+
lib/java_buildpack/util/cache/*.rb
28+
lib/java_buildpack/util/play/*.rb)).freeze
29+
1630
require 'rspec/core/rake_task'
1731
RSpec::Core::RakeTask.new
1832

1933
require 'yard'
20-
YARD::Rake::YardocTask.new
34+
YARD::Rake::YardocTask.new do |t|
35+
t.files = RUBY_FILES
36+
end
2137

2238
require 'rubocop/rake_task'
2339
Rubocop::RakeTask.new
2440

2541
require 'open3'
2642
task :check_api_doc do
2743
puts "\nChecking API documentation..."
28-
output = Open3.capture3("yard stats --list-undoc")[0]
44+
output = Open3.capture3("yard stats --list-undoc -- #{RUBY_FILES.join(' ')}")[0]
2945
if output !~ /100.00% documented/
3046
puts "\nFailed due to undocumented public API:\n\n#{output}"
3147
exit 1

‎lib/java_buildpack/component/additional_libraries.rb‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,7 @@ def as_classpath
4545
# Symlink the contents of the collection to a destination directory.
4646
#
4747
# @param [Pathname] destination the destination to link to
48+
# @return [void]
4849
def link_to(destination)
4950
FileUtils.mkdir_p destination
5051
each { |path| (destination + path.basename).make_symlink(path.relative_path_from(destination)) }

‎lib/java_buildpack/component/application.rb‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -29,21 +29,21 @@ module JavaBuildpack::Component
2929
class Application
3030

3131
# @!attribute [r] details
32-
# @return [Hash] the parsed contents of the +VCAP_APPLICATION+ environment variable
32+
# @return [Hash] the parsed contents of the +VCAP_APPLICATION+ environment variable
3333
attr_reader :details
3434

3535
# @!attribute [r] environment
36-
# @return [Hash] all environment variables except +VCAP_APPLICATION+ and +VCAP_SERVICES+. Those values are
37-
# available separately in parsed form.
36+
# @return [Hash] all environment variables except +VCAP_APPLICATION+ and +VCAP_SERVICES+. Those values are
37+
# available separately in parsed form.
3838
attr_reader :environment
3939

4040
# @!attribute [r] root
41-
# @return [JavaBuildpack::Util::FilteringPathname] the root of the application's fileystem filtered so that it
42-
# only shows files that have been uploaded by the user
41+
# @return [JavaBuildpack::Util::FilteringPathname] the root of the application's fileystem filtered so that it
42+
# only shows files that have been uploaded by the user
4343
attr_reader :root
4444

4545
# @!attribute [r] services
46-
# @return [Hash] the parsed contents of the +VCAP_SERVICES+ environment variable
46+
# @return [Hash] the parsed contents of the +VCAP_SERVICES+ environment variable
4747
attr_reader :services
4848

4949
# Create a new instance of the application abstraction

‎lib/java_buildpack/component/base_component.rb‎

Lines changed: 21 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -42,32 +42,35 @@ def initialize(context)
4242
@droplet = context[:droplet]
4343
end
4444

45-
# If the component should be used when staging an application
45+
# @!macro [new] base_component_detect
46+
# If the component should be used when staging an application
4647
#
47-
# @return [Array<String>, String, nil] If the component should be used when staging the application, a +String+ or
48-
# an +Array<String>+ that uniquely identifies the component (e.g.
49-
# +open_jdk=1.7.0_40+). Otherwise, +nil+.
48+
# @return [Array<String>, String, nil] If the component should be used when staging the application, a +String+ or
49+
# an +Array<String>+ that uniquely identifies the component (e.g.
50+
# +open_jdk=1.7.0_40+). Otherwise, +nil+.
5051
def detect
5152
fail "Method 'detect' must be defined"
5253
end
5354

54-
# Modifies the application's file system. The component is expected to transform the application's file system in
55-
# whatever way is necessary (e.g. downloading files or creating symbolic links) to support the function of the
56-
# component. Status output written to +STDOUT+ is expected as part of this invocation.
55+
# @!macro [new] base_component_compile
56+
# Modifies the application's file system. The component is expected to transform the application's file system in
57+
# whatever way is necessary (e.g. downloading files or creating symbolic links) to support the function of the
58+
# component. Status output written to +STDOUT+ is expected as part of this invocation.
5759
#
58-
# @return [void]
60+
# @return [void]
5961
def compile
6062
fail "Method 'compile' must be defined"
6163
end
6264

63-
# Modifies the application's runtime configuration. The component is expected to transform members of the +context+
64-
# (e.g. +@java_home+, +@java_opts+, etc.) in whatever way is necessary to support the function of the component.
65+
# @!macro [new] base_component_release
66+
# Modifies the application's runtime configuration. The component is expected to transform members of the +context+
67+
# (e.g. +@java_home+, +@java_opts+, etc.) in whatever way is necessary to support the function of the component.
6568
#
66-
# Container components are also expected to create the command required to run the application. These components
67-
# are expected to read the +context+ values and take them into account when creating the command.
69+
# Container components are also expected to create the command required to run the application. These components
70+
# are expected to read the +context+ values and take them into account when creating the command.
6871
#
69-
# @return [void, String] components other than containers are not expected to return any value. Container
70-
# components are expected to return the command required to run the application.
72+
# @return [void, String] components other than containers are not expected to return any value. Container
73+
# components are expected to return the command required to run the application.
7174
def release
7275
fail "Method 'release' must be defined"
7376
end
@@ -98,6 +101,7 @@ def download(version, uri, name = @component_name, &block)
98101
# @param [String] jar_name the name to save the jar as
99102
# @param [Pathname] target_directory the directory to store the JAR file in. Defaults to the component's sandbox.
100103
# @param [String] name an optional name for the download. Defaults to +@component_name+.
104+
# @return [void]
101105
def download_jar(version, uri, jar_name, target_directory = @droplet.sandbox, name = @component_name)
102106
download(version, uri, name) do |file|
103107
FileUtils.mkdir_p target_directory
@@ -111,6 +115,7 @@ def download_jar(version, uri, jar_name, target_directory = @droplet.sandbox, na
111115
# @param [String] uri the uri of the download
112116
# @param [Pathname] target_directory the directory to expand the TAR file to. Defaults to the component's sandbox.
113117
# @param [String] name an optional name for the download and expansion. Defaults to +@component_name+.
118+
# @return [void]
114119
def download_tar(version, uri, target_directory = @droplet.sandbox, name = @component_name)
115120
download(version, uri, name) do |file|
116121
with_timing "Expanding #{name} to #{target_directory.relative_path_from(@droplet.root)}" do
@@ -125,6 +130,7 @@ def download_tar(version, uri, target_directory = @droplet.sandbox, name = @comp
125130
# @param [Boolean] strip_top_level whether to strip the top-level directory when expanding. Defaults to +true+.
126131
# @param [Pathname] target_directory the directory to expand the ZIP file to. Defaults to the component's sandbox.
127132
# @param [String] name an optional name for the download. Defaults to +@component_name+.
133+
# @return [void]
128134
def download_zip(version, uri, strip_top_level = true, target_directory = @droplet.sandbox, name = @component_name)
129135
download(version, uri, name) do |file|
130136
with_timing "Expanding #{name} to #{target_directory.relative_path_from(@droplet.root)}" do
@@ -146,6 +152,7 @@ def download_zip(version, uri, strip_top_level = true, target_directory = @dropl
146152
# Wrap the execution of a block with timing information
147153
#
148154
# @param [String] caption the caption to print when timing starts
155+
# @return [void]
149156
def with_timing(caption)
150157
start_time = Time.now
151158
print " #{caption} "

‎lib/java_buildpack/component/droplet.rb‎

Lines changed: 12 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -30,31 +30,31 @@ module JavaBuildpack::Component
3030
class Droplet
3131

3232
# @!attribute [r] additional_libraries
33-
# @return [AdditionalLibraries] the shared +AdditionalLibraries+ instance for all components
33+
# @return [AdditionalLibraries] the shared +AdditionalLibraries+ instance for all components
3434
attr_reader :additional_libraries
3535

3636
# @!attribute [r] component_id
37-
# @return [String] the id of component using this droplet
37+
# @return [String] the id of component using this droplet
3838
attr_reader :component_id
3939

4040
# @!attribute [r] java_home
41-
# @return [ImmutableJavaHome, MutableJavaHome] the shared +JavaHome+ instance for all components. If the
42-
# component using this instance is a jre, then this will be an
43-
# instance of +MutableJavaHome+. Otherwise it will be an instance of
44-
# +ImmutableJavaHome+.
41+
# @return [ImmutableJavaHome, MutableJavaHome] the shared +JavaHome+ instance for all components. If the
42+
# component using this instance is a jre, then this will be an
43+
# instance of +MutableJavaHome+. Otherwise it will be an instance of
44+
# +ImmutableJavaHome+.
4545
attr_reader :java_home
4646

4747
# @!attribute [r] java_opts
48-
# @return [JavaOpts] the shared +JavaOpts+ instance for all components
48+
# @return [JavaOpts] the shared +JavaOpts+ instance for all components
4949
attr_reader :java_opts
5050

5151
# @!attribute [r] root
52-
# @return [JavaBuildpack::Util::FilteringPathname] the root of the droplet's fileystem filtered so that it
53-
# excludes files in the sandboxes of other components
52+
# @return [JavaBuildpack::Util::FilteringPathname] the root of the droplet's fileystem filtered so that it
53+
# excludes files in the sandboxes of other components
5454
attr_reader :root
5555

5656
# @!attribute [r] sandbox
57-
# @return [Pathname] the root of the component's sandbox
57+
# @return [Pathname] the root of the component's sandbox
5858
attr_reader :sandbox
5959

6060
# Creates a new instance of the droplet abstraction
@@ -85,7 +85,8 @@ def initialize(additional_libraries, component_id, java_home, java_opts, root)
8585

8686
# Copy resources from a components resources directory to a directory
8787
#
88-
# @param [Pathname] target_directory the directory to copy to. Default to a component's +sandbox+
88+
# @param [Pathname] target_directory the directory to copy to. Defaults to the component's +sandbox+.
89+
# @return [void]
8990
def copy_resources(target_directory = @sandbox)
9091
resources = RESOURCES_DIRECTORY + @component_id
9192

‎lib/java_buildpack/component/immutable_java_home.rb‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,7 @@ def as_env_var
4444
# Execute a block with the +JAVA_HOME+ environment variable set
4545
#
4646
# @yield yields to block with the +JAVA_HOME+ environment variable set
47+
# @return [Object] the returned value of the block
4748
def do_with
4849
previous_value = ENV['JAVA_HOME']
4950
begin

‎lib/java_buildpack/component/mutable_java_home.rb‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ module JavaBuildpack::Component
2525
class MutableJavaHome
2626

2727
# @!attribute [rw] root
28-
# @return [String] the root of the droplet's +JAVA_HOME+
28+
# @return [String] the root of the droplet's +JAVA_HOME+
2929
attr_accessor :root
3030

3131
end

‎lib/java_buildpack/component/versioned_dependency_component.rb‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,9 @@ class VersionedDependencyComponent < BaseComponent
2929

3030
# Creates an instance. In addition to the functionality inherited from +BaseComponent+, +@version+ and +@uri+
3131
# instance variables are exposed.
32+
#
33+
# @param [Hash] context a collection of utilities used by components
34+
# @param [Block, nil] version_validator an optional version validation block
3235
def initialize(context, &version_validator)
3336
super(context)
3437

@@ -52,9 +55,10 @@ def detect
5255

5356
protected
5457

55-
# Whether or not this component supports this application
58+
# @!macro [new] versioned_dependency_component_supports
59+
# Whether or not this component supports this application
5660
#
57-
# @return [Boolean] whether or not this component supports this application
61+
# @return [Boolean] whether or not this component supports this application
5862
def supports?
5963
fail "Method 'supports?' must be defined"
6064
end
@@ -64,6 +68,7 @@ def supports?
6468
# @param [String] jar_name the name to save the jar as
6569
# @param [Pathname] target_directory the directory to store the JAR file in. Defaults to the component's sandbox.
6670
# @param [String] name an optional name for the download. Defaults to +@component_name+.
71+
# @return [void]
6772
def download_jar(jar_name = jar_name, target_directory = @droplet.sandbox, name = @component_name)
6873
super(@version, @uri, jar_name, target_directory, name)
6974
end
@@ -72,6 +77,7 @@ def download_jar(jar_name = jar_name, target_directory = @droplet.sandbox, name
7277
#
7378
# @param [Pathname] target_directory the directory to expand the TAR file to. Defaults to the component's sandbox.
7479
# @param [String] name an optional name for the download and expansion. Defaults to +@component_name+.
80+
# @return [void]
7581
def download_tar(target_directory = @droplet.sandbox, name = @component_name)
7682
super(@version, @uri, target_directory, name)
7783
end
@@ -81,11 +87,14 @@ def download_tar(target_directory = @droplet.sandbox, name = @component_name)
8187
# @param [Boolean] strip_top_level whether to strip the top-level directory when expanding. Defaults to +true+.
8288
# @param [Pathname] target_directory the directory to expand the ZIP file to. Defaults to the component's sandbox.
8389
# @param [String] name an optional name for the download. Defaults to +@component_name+.
90+
# @return [void]
8491
def download_zip(strip_top_level = true, target_directory = @droplet.sandbox, name = @component_name)
8592
super(@version, @uri, strip_top_level, target_directory, name)
8693
end
8794

8895
# A generated JAR name for the component. Meets the format +<component-id>-<version>.jar+
96+
#
97+
# @return [String] a generated JAR name for the component
8998
def jar_name
9099
"#{@droplet.component_id}-#{@version}.jar"
91100
end

‎lib/java_buildpack/container/groovy.rb‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,14 +30,19 @@ module JavaBuildpack::Container
3030
class Groovy < JavaBuildpack::Component::VersionedDependencyComponent
3131
include JavaBuildpack::Util
3232

33+
# Creates an instance
34+
#
35+
# @param [Hash] context a collection of utilities used the component
3336
def initialize(context)
3437
super(context) { |candidate_version| candidate_version.check_size(3) }
3538
end
3639

40+
# @macro base_component_compile
3741
def compile
3842
download_zip
3943
end
4044

45+
# @macro base_component_release
4146
def release
4247
[
4348
@droplet.java_home.as_env_var,
@@ -51,6 +56,7 @@ def release
5156

5257
protected
5358

59+
# @macro versioned_dependency_component_supports
5460
def supports?
5561
JavaBuildpack::Util::ClassFileUtils.class_files(@application).empty? && main_groovy
5662
end

‎lib/java_buildpack/container/java_main.rb‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,13 +26,16 @@ module JavaBuildpack::Container
2626
# +main()+ applications.
2727
class JavaMain < JavaBuildpack::Component::BaseComponent
2828

29+
# @macro base_component_detect
2930
def detect
3031
main_class ? JavaMain.to_s.dash_case : nil
3132
end
3233

34+
# @macro base_component_compile
3335
def compile
3436
end
3537

38+
# @macro base_component_release
3639
def release
3740
@droplet.additional_libraries.insert 0, @application.root
3841
manifest_class_path.each { |path| @droplet.additional_libraries << path }

0 commit comments

Comments
 (0)