Skip to content

Commit 34705ac

Browse files
nebhalenebhale
committed
Use Yard (see ...) syntax
Based on the results of lsegal/yard#720 (comment) the Yard (see ...) syntax suits our needs. This change updates all of our docs to remove the macros and instead use that syntax. [#68083978]
1 parent c5b2c3c commit 34705ac

45 files changed

Lines changed: 154 additions & 178 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: 2 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -13,35 +13,19 @@
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-
3016
require 'rspec/core/rake_task'
3117
RSpec::Core::RakeTask.new
3218

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

3822
require 'rubocop/rake_task'
3923
Rubocop::RakeTask.new
4024

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

‎docs/extending-base_component.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ def detect
1515
# whatever way is necessary (e.g. downloading files or creating symbolic links) to support the function of the
1616
# component. Status output written to +STDOUT+ is expected as part of this invocation.
1717
#
18-
# @return [void]
18+
# @return [Void]
1919
def compile
2020

2121
# Modifies the application's runtime configuration. The component is expected to transform members of the +context+
@@ -47,7 +47,7 @@ def release
4747
# @param [JavaBuildpack::Util::TokenizedVersion] version
4848
# @param [String] uri
4949
# @param [String] name an optional name for the download. Defaults to +@component_name+.
50-
# @return [void]
50+
# @return [Void]
5151
def download(version, uri, name = @component_name, &block)
5252

5353
# Downloads a given JAR file and stores it.

‎docs/extending-caches.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,13 +20,13 @@ Many components will want to cache large files that are downloaded for applicati
2020
# item is already in the cache, to validate that the item is up to date
2121
# @yieldparam [File] file the file representing the cached item. In order to ensure that the file is not changed or
2222
# deleted while it is being used, the cached item can only be accessed as part of a block.
23-
# @return [void]
23+
# @return [Void]
2424
def get(uri)
2525

2626
# Remove an item from the cache
2727
#
2828
# @param [String] uri the URI of the item to remove
29-
# @return [void]
29+
# @return [Void]
3030
def evict(uri)
3131
```
3232

‎docs/extending-versioned_dependency_component.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ This base class is recommended for use by any component that uses the buildpack
88
# whatever way is necessary (e.g. downloading files or creating symbolic links) to support the function of the
99
# component. Status output written to +STDOUT+ is expected as part of this invocation.
1010
#
11-
# @return [void]
11+
# @return [Void]
1212
def compile
1313

1414
# Modifies the application's runtime configuration. The component is expected to transform members of the +context+
@@ -48,7 +48,7 @@ def supports?
4848
# @param [JavaBuildpack::Util::TokenizedVersion] version
4949
# @param [String] uri
5050
# @param [String] name an optional name for the download. Defaults to +@component_name+.
51-
# @return [void]
51+
# @return [Void]
5252
def download(version, uri, name = @component_name, &block)
5353

5454
# Downloads a given JAR file and stores it.

‎docs/extending.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ def detect
2424
# whatever way is necessary (e.g. downloading files or creating symbolic links) to support the function of the
2525
# component. Status output written to +STDOUT+ is expected as part of this invocation.
2626
#
27-
# @return [void]
27+
# @return [Void]
2828
def compile
2929

3030
# Modifies the application's runtime configuration. The component is expected to transform members of the +droplet+

‎lib/java_buildpack/buildpack.rb‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ def detect
5252

5353
# Transforms the application directory such that the JRE, container, and frameworks can run the application
5454
#
55-
# @return [void]
55+
# @return [Void]
5656
def compile
5757
diagnose_git_info true
5858

‎lib/java_buildpack/component/additional_libraries.rb‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ def as_classpath
4646
# Symlink the contents of the collection to a destination directory.
4747
#
4848
# @param [Pathname] destination the destination to link to
49-
# @return [void]
49+
# @return [Void]
5050
def link_to(destination)
5151
FileUtils.mkdir_p destination
5252
each { |path| (destination + path.basename).make_symlink(path.relative_path_from(destination)) }

‎lib/java_buildpack/component/base_component.rb‎

Lines changed: 19 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -43,35 +43,32 @@ def initialize(context)
4343
@droplet = context[:droplet]
4444
end
4545

46-
# @!macro [new] base_component_detect
47-
# If the component should be used when staging an application
46+
# If the component should be used when staging an application
4847
#
49-
# @return [Array<String>, String, nil] If the component should be used when staging the application, a +String+ or
50-
# an +Array<String>+ that uniquely identifies the component (e.g.
51-
# +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+.
5251
def detect
5352
fail "Method 'detect' must be defined"
5453
end
5554

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

66-
# @!macro [new] base_component_release
67-
# Modifies the application's runtime configuration. The component is expected to transform members of the +context+
68-
# (e.g. +@java_home+, +@java_opts+, etc.) in whatever way is necessary to support the function of the component.
64+
# Modifies the application's runtime configuration. The component is expected to transform members of the +context+
65+
# (e.g. +@java_home+, +@java_opts+, etc.) in whatever way is necessary to support the function of the component.
6966
#
70-
# Container components are also expected to create the command required to run the application. These components
71-
# are expected to read the +context+ values and take them into account when creating the command.
67+
# Container components are also expected to create the command required to run the application. These components
68+
# are expected to read the +context+ values and take them into account when creating the command.
7269
#
73-
# @return [void, String] components other than containers are not expected to return any value. Container
74-
# components are expected to return the command required to run the application.
70+
# @return [void, String] components other than containers are not expected to return any value. Container
71+
# components are expected to return the command required to run the application.
7572
def release
7673
fail "Method 'release' must be defined"
7774
end
@@ -84,7 +81,7 @@ def release
8481
# @param [JavaBuildpack::Util::TokenizedVersion] version
8582
# @param [String] uri
8683
# @param [String] name an optional name for the download. Defaults to +@component_name+.
87-
# @return [void]
84+
# @return [Void]
8885
def download(version, uri, name = @component_name, &block)
8986
download_start_time = Time.now
9087
print "-----> Downloading #{name} #{version} from #{uri} "
@@ -102,7 +99,7 @@ def download(version, uri, name = @component_name, &block)
10299
# @param [String] jar_name the name to save the jar as
103100
# @param [Pathname] target_directory the directory to store the JAR file in. Defaults to the component's sandbox.
104101
# @param [String] name an optional name for the download. Defaults to +@component_name+.
105-
# @return [void]
102+
# @return [Void]
106103
def download_jar(version, uri, jar_name, target_directory = @droplet.sandbox, name = @component_name)
107104
download(version, uri, name) do |file|
108105
FileUtils.mkdir_p target_directory
@@ -116,7 +113,7 @@ def download_jar(version, uri, jar_name, target_directory = @droplet.sandbox, na
116113
# @param [String] uri the uri of the download
117114
# @param [Pathname] target_directory the directory to expand the TAR file to. Defaults to the component's sandbox.
118115
# @param [String] name an optional name for the download and expansion. Defaults to +@component_name+.
119-
# @return [void]
116+
# @return [Void]
120117
def download_tar(version, uri, target_directory = @droplet.sandbox, name = @component_name)
121118
download(version, uri, name) do |file|
122119
with_timing "Expanding #{name} to #{target_directory.relative_path_from(@droplet.root)}" do
@@ -131,7 +128,7 @@ def download_tar(version, uri, target_directory = @droplet.sandbox, name = @comp
131128
# @param [Boolean] strip_top_level whether to strip the top-level directory when expanding. Defaults to +true+.
132129
# @param [Pathname] target_directory the directory to expand the ZIP file to. Defaults to the component's sandbox.
133130
# @param [String] name an optional name for the download. Defaults to +@component_name+.
134-
# @return [void]
131+
# @return [Void]
135132
def download_zip(version, uri, strip_top_level = true, target_directory = @droplet.sandbox, name = @component_name)
136133
download(version, uri, name) do |file|
137134
with_timing "Expanding #{name} to #{target_directory.relative_path_from(@droplet.root)}" do
@@ -153,7 +150,7 @@ def download_zip(version, uri, strip_top_level = true, target_directory = @dropl
153150
# Wrap the execution of a block with timing information
154151
#
155152
# @param [String] caption the caption to print when timing starts
156-
# @return [void]
153+
# @return [Void]
157154
def with_timing(caption)
158155
start_time = Time.now
159156
print " #{caption} "

‎lib/java_buildpack/component/droplet.rb‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -87,7 +87,7 @@ def initialize(additional_libraries, component_id, java_home, java_opts, root)
8787
# Copy resources from a components resources directory to a directory
8888
#
8989
# @param [Pathname] target_directory the directory to copy to. Defaults to the component's +sandbox+.
90-
# @return [void]
90+
# @return [Void]
9191
def copy_resources(target_directory = @sandbox)
9292
resources = RESOURCES_DIRECTORY + @component_id
9393

‎lib/java_buildpack/component/modular_component.rb‎

Lines changed: 12 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -39,39 +39,37 @@ def initialize(context, &version_validator)
3939
@sub_components = supports? ? sub_components(context) : []
4040
end
4141

42-
# @macro base_component_detect
42+
# (see JavaBuildpack::Component::BaseComponent#detect)
4343
def detect
4444
supports? ? @sub_components.map { |m| m.detect }.flatten.compact : nil
4545
end
4646

47-
# @macro base_component_compile
47+
# (see JavaBuildpack::Component::BaseComponent#compile)
4848
def compile
4949
@sub_components.each { |m| m.compile }
5050
end
5151

52-
# @macro base_component_release
52+
# (see JavaBuildpack::Component::BaseComponent#release)
5353
def release
5454
@sub_components.map { |m| m.release }
5555
command
5656
end
5757

5858
protected
5959

60-
# @!macro [new] modular_component_command
61-
# The command for this component
60+
# The command for this component
6261
#
63-
# @return [void, String] components other than containers are not expected to return any value. Container
64-
# components are expected to return the command required to run the application.
62+
# @return [void, String] components other than containers are not expected to return any value. Container
63+
# components are expected to return the command required to run the application.
6564
def command
6665
fail "Method 'command' must be defined"
6766
end
6867

69-
# @!macro [new] modular_component_sub_components
70-
# The sub_components that make up this component
68+
# The sub_components that make up this component
7169
#
72-
# @param [Hash] context the context of the component
73-
# @return [Array<BaseComponent>] a collection of +BaseComponent+s that make up the sub_components of this
74-
# component
70+
# @param [Hash] context the context of the component
71+
# @return [Array<BaseComponent>] a collection of +BaseComponent+s that make up the sub_components of this
72+
# component
7573
def sub_components(context)
7674
fail "Method 'sub_components' must be defined"
7775
end
@@ -87,10 +85,9 @@ def sub_configuration_context(context, key)
8785
c
8886
end
8987

90-
# @!macro [new] modular_component_supports
91-
# Whether or not this component supports this application
88+
# Whether or not this component supports this application
9289
#
93-
# @return [Boolean] whether or not this component supports this application
90+
# @return [Boolean] whether or not this component supports this application
9491
def supports?
9592
fail "Method 'supports?' must be defined"
9693
end

0 commit comments

Comments
 (0)