Merge pull request #82 from DataDog/anmarchenko/yard_docs

generate YARD documentation

.github/workflows/yard.yml

@@ -2,7 +2,7 @@ name: Deploy Yard documentation to Pages
 
 on:
   push:
-    branches: ['release']
+    branches: ['main']
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:

.yardopts

@@ -1,3 +1,12 @@
+--markup markdown
+--markup-provider redcarpet
 --readme README.md
+--tag configure_with:"Configure with"
+--tag default:"Defaults to"
+--tag 'public_api:Public API'
+--hide-tag public_api
 --files LICENSE
+--files docs/Deprecation.md
+--files docs/PublicApi.md
+--template-path yard/templates
 -e ./yard/extensions.rb

Gemfile

@@ -23,6 +23,7 @@ gem "timecop"
 gem "standard", "~> 1.31"
 
 gem "yard"
+gem "redcarpet" if RUBY_PLATFORM != "java"
 gem "webrick"
 gem "pimpmychangelog", ">= 0.1.2"
 

README.md

@@ -1,6 +1,7 @@
 # Datadog CI Visibility for Ruby
 
 [![Gem Version](https://badge.fury.io/rb/datadog-ci.svg)](https://badge.fury.io/rb/datadog-ci)
+[![YARD documentation](https://img.shields.io/badge/YARD-documentation-blue)](https://datadoghq.dev/datadog-ci-rb/)
 [![codecov](https://codecov.io/gh/DataDog/datadog-ci-rb/branch/main/graph/badge.svg)](https://app.codecov.io/gh/DataDog/datadog-ci-rb/branch/main)
 [![CircleCI](https://dl.circleci.com/status-badge/img/gh/DataDog/datadog-ci-rb/tree/main.svg?style=svg)](https://dl.circleci.com/status-badge/redirect/gh/DataDog/datadog-ci-rb/tree/main)
 

docs/Deprecation.md

@@ -0,0 +1,8 @@
+# Deprecation
+
+Deprecated API objects are scheduled to be **removed in the next major version release**.
+
+Deprecated objects can still be safely used until the next major version.
+
+Objects will receive the deprecation tag in a minor version release,
+allowing for deprecation warnings to be surfaced to users before the next major release.

docs/PublicApi.md

@@ -0,0 +1,14 @@
+# Public API
+
+`datadog-ci` respects [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html).
+
+Classes, modules, and methods marked as part of the public API will not introduce
+breaking changes outside of a major version release.
+
+Objects that belong to the public API are marked with the `@public_api` YARD documentation tag.
+When navigating [`datadog-ci`'s YARD documentation](https://rubydoc.info/gems/datadog-ci), public API
+objects will have an explicit banner informing the user that they are part of the public API contract.
+
+Objects not marked with the `@public_api` tag are not part of the public API contract, and thus
+considered internal to `datadog-ci`. These objects can receive breaking changes in minor and patch
+releases.

lib/datadog/ci.rb

@@ -10,14 +10,14 @@ module Datadog
   # @public_api
   module CI
     class << self
-      # Starts a {Datadog::CI::TestSesstion ci_test_session} that represents the whole test session run.
+      # Starts a {Datadog::CI::TestSession ci_test_session} that represents the whole test session run.
       #
       # Read Datadog documentation on test sessions
       # [here](https://docs.datadoghq.com/continuous_integration/explorer/?tab=testruns#sessions).
       #
       # Returns the existing test session if one is already active. There is at most a single test session per process.
       #
-      # The {#start_test_session} method is used to mark the start of the test session:
+      # The {.start_test_session} method is used to mark the start of the test session:
       # ```
       # Datadog::CI.start_test_session(
       #   service: "my-web-site-tests",
@@ -35,8 +35,6 @@ class << self
       # @return [Datadog::CI::TestSession] returns the active, running {Datadog::CI::TestSession}.
       # @return [Datadog::CI::NullSpan] ci_span null object if CI visibility is disabled or if old Datadog agent is
       #         detected and test suite level visibility cannot be supported.
-      #
-      # @public_api
       def start_test_session(service: nil, tags: {})
         service ||= Datadog.configuration.service
         recorder.start_test_session(service: service, tags: tags)
@@ -67,13 +65,13 @@ def active_test_session
       # Starts a {Datadog::CI::TestModule ci_test_module} that represents a single test module (for most Ruby test frameworks
       # module will correspond 1-1 to the test session).
       #
-      # Read Datadog documentation on test modules:
+      # Read Datadog documentation on test modules
       # [here](https://docs.datadoghq.com/continuous_integration/explorer/?tab=testruns#module).
       #
       # Returns the existing test session if one is already active. There is at most a single test module per process
       # active at any given time.
       #
-      # The {#start_test_module} method is used to mark the start of the test session:
+      # The {.start_test_module} method is used to mark the start of the test session:
       # ```
       # Datadog::CI.start_test_module(
       #   "my-module",
@@ -93,8 +91,6 @@ def active_test_session
       # @return [Datadog::CI::TestModule] returns the active, running {Datadog::CI::TestModule}.
       # @return [Datadog::CI::NullSpan] ci_span null object if CI visibility is disabled or if old Datadog agent is
       #         detected and test suite level visibility cannot be supported.
-      #
-      # @public_api
       def start_test_module(test_module_name, service: nil, tags: {})
         recorder.start_test_module(test_module_name, service: service, tags: tags)
       end
@@ -125,10 +121,10 @@ def active_test_module
       # Starts a {Datadog::CI::TestSuite ci_test_suite} that represents a single test suite.
       # If a test suite with given name is running, returns the existing test suite.
       #
-      # Read Datadog documentation on test suites:
+      # Read Datadog documentation on test suites
       # [here](https://docs.datadoghq.com/continuous_integration/explorer/?tab=testruns#module).
       #
-      # The {#start_test_suite} method is used to mark the start of a test suite:
+      # The {.start_test_suite} method is used to mark the start of a test suite:
       # ```
       # Datadog::CI.start_test_suite(
       #   "calculator_tests",
@@ -148,8 +144,6 @@ def active_test_module
       # @return [Datadog::CI::TestSuite] returns the active, running {Datadog::CI::TestSuite}.
       # @return [Datadog::CI::NullSpan] ci_span null object if CI visibility is disabled or if old Datadog agent is
       #         detected and test suite level visibility cannot be supported.
-      #
-      # @public_api
       def start_test_suite(test_suite_name, service: nil, tags: {})
         recorder.start_test_suite(test_suite_name, service: service, tags: tags)
       end
@@ -188,6 +182,7 @@ def active_test_suite(test_suite_name)
       # ```
       # Datadog::CI.trace_test(
       #   "test_add_two_numbers",
+      #   "calculator_tests",
       #   service: "my-web-site-tests",
       #   tags: { Datadog::CI::Ext::Test::TAG_FRAMEWORK => "my-test-framework" }
       # ) do |ci_test|
@@ -201,59 +196,57 @@ def active_test_suite(test_suite_name)
       # end
       # ```
       #
-      # The {#trace_test} method can also be used without a block in this way:
+      # The {.trace_test} method can also be used without a block in this way:
       # ```
       # ci_test = Datadog::CI.trace_test(
-      #   "test_add_two_numbers',
+      #   "test_add_two_numbers",
+      #   "calculator_tests",
       #   service: "my-web-site-tests",
       #   tags: { Datadog::CI::Ext::Test::TAG_FRAMEWORK => "my-test-framework" }
       # )
-      # run_test
+      # # ... run test here ...
       # ci_test.finish
       # ```
       #
       # Remember that in this case, calling {Datadog::CI::Test#finish} is mandatory.
       #
       # @param [String] test_name {Datadog::CI::Test} name (example: "test_add_two_numbers").
       # @param [String] test_suite_name name of test suite this test belongs to (example: "CalculatorTest").
-      # @param [String] service the service name for this test
+      # @param [String] service the service name for this test (optional, inherited from test session if not provided)
       # @param [Hash<String,String>] tags extra tags which should be added to the test.
       # @return [Object] If a block is provided, returns the result of the block execution.
       # @return [Datadog::CI::Test] If no block is provided, returns the active,
       #         unfinished {Datadog::CI::Test}.
       # @return [Datadog::CI::NullSpan] ci_span null object if CI visibility is disabled
-      # @yield Optional block where new newly created {Datadog::CI::Test} captures the execution.
+      # @yield Optional block where newly created {Datadog::CI::Test} captures the execution.
       # @yieldparam [Datadog::CI::Test] ci_test the newly created and active [Datadog::CI::Test]
       # @yieldparam [Datadog::CI::NullSpan] ci_span null object if CI visibility is disabled
-      #
-      # @public_api
       def trace_test(test_name, test_suite_name, service: nil, tags: {}, &block)
         recorder.trace_test(test_name, test_suite_name, service: service, tags: tags, &block)
       end
 
-      # Same as {#trace_test} but it does not accept a block.
+      # Same as {.trace_test} but it does not accept a block.
       # Raises an error if a test is already active.
       #
       # Usage:
       #
       # ```
       # ci_test = Datadog::CI.start_test(
-      #   "test_add_two_numbers',
+      #   "test_add_two_numbers",
+      #   "calculator_tests",
       #   service: "my-web-site-tests",
       #   tags: { Datadog::CI::Ext::Test::TAG_FRAMEWORK => "my-test-framework" }
       # )
-      # run_test
+      # # ... run test here ...
       # ci_test.finish
       # ```
       #
       # @param [String] test_name {Datadog::CI::Test} name (example: "test_add_two_numbers").
       # @param [String] test_suite_name name of test suite this test belongs to (example: "CalculatorTest").
-      # @param [String] service the service name for this span.
+      # @param [String] service the service name for this span (optional, inherited from test session if not provided)
       # @param [Hash<String,String>] tags extra tags which should be added to the test.
       # @return [Datadog::CI::Test] Returns the active, unfinished {Datadog::CI::Test}.
       # @return [Datadog::CI::NullSpan] ci_span null object if CI visibility is disabled
-      #
-      # @public_api
       def start_test(test_name, test_suite_name, service: nil, tags: {})
         recorder.trace_test(test_name, test_suite_name, service: service, tags: tags)
       end
@@ -275,14 +268,14 @@ def start_test(test_name, test_suite_name, service: nil, tags: {})
       # end
       # ```
       #
-      # The {#trace} method can also be used without a block in this way:
+      # The {.trace} method can also be used without a block in this way:
       # ```
       # ci_span = Datadog::CI.trace(
       #   "step",
       #   "Given I have 42 cucumbers",
       #   tags: {}
       # )
-      # run_test
+      # # ... run test here ...
       # ci_span.finish
       # ```
       # Remember that in this case, calling {Datadog::CI::Span#finish} is mandatory.
@@ -294,11 +287,9 @@ def start_test(test_name, test_suite_name, service: nil, tags: {})
       # @return [Datadog::CI::Span] If no block is provided, returns the active,
       #         unfinished {Datadog::CI::Span}.
       # @return [Datadog::CI::NullSpan] ci_span null object if CI visibility is disabled
-      # @yield Optional block where new newly created {Datadog::CI::Span} captures the execution.
+      # @yield Optional block where newly created {Datadog::CI::Span} captures the execution.
       # @yieldparam [Datadog::CI::Span] ci_span the newly created and active [Datadog::CI::Span]
       # @yieldparam [Datadog::CI::NullSpan] ci_span null object if CI visibility is disabled
-      #
-      # @public_api
       def trace(span_type, span_name, tags: {}, &block)
         recorder.trace(span_type, span_name, tags: tags, &block)
       end
@@ -338,7 +329,8 @@ def active_span(span_type)
       # ```
       # # start a test
       # Datadog::CI.start_test(
-      #   "test_add_two_numbers',
+      #   "test_add_two_numbers",
+      #   "calculator_tests",
       #   service: "my-web-site-tests",
       #   tags: { Datadog::CI::Ext::Test::TAG_FRAMEWORK => "my-test-framework" }
       # )
@@ -355,22 +347,26 @@ def active_test
         recorder.active_test
       end
 
-      # Internal only, to finish a test use Datadog::CI::Test#finish
+      # Internal only, to finish a test use {Datadog::CI::Test#finish}
+      # @private
       def deactivate_test(test)
         recorder.deactivate_test(test)
       end
 
-      # Internal only, to finish a test session use Datadog::CI::TestSession#finish
+      # Internal only, to finish a test session use {Datadog::CI::TestSession#finish}
+      # @private
       def deactivate_test_session
         recorder.deactivate_test_session
       end
 
-      # Internal only, to finish a test module use Datadog::CI::TestModule#finish
+      # Internal only, to finish a test module use {Datadog::CI::TestModule#finish}
+      # @private
       def deactivate_test_module
         recorder.deactivate_test_module
       end
 
-      # Internal only, to finish a test suite use Datadog::CI::TestSuite#finish
+      # Internal only, to finish a test suite use {Datadog::CI::TestSuite#finish}
+      # @private
       def deactivate_test_suite(test_suite_name)
         recorder.deactivate_test_suite(test_suite_name)
       end

lib/datadog/ci/contrib/cucumber/configuration/settings.rb

@@ -11,7 +11,7 @@ module Contrib
       module Cucumber
         module Configuration
           # Custom settings for the Cucumber integration
-          # TODO: mark as `@public_api` when GA
+          # @public_api
           class Settings < Datadog::CI::Contrib::Settings
             option :enabled do |o|
               o.type :bool
@@ -24,6 +24,7 @@ class Settings < Datadog::CI::Contrib::Settings
               o.default { Datadog.configuration.service_without_fallback || Ext::SERVICE_NAME }
             end
 
+            # @deprecated Will be removed in 1.0
             option :operation_name do |o|
               o.type :string
               o.env Ext::ENV_OPERATION_NAME

lib/datadog/ci/contrib/minitest/configuration/settings.rb

@@ -9,7 +9,7 @@ module Contrib
       module Minitest
         module Configuration
           # Custom settings for the Minitest integration
-          # TODO: mark as `@public_api` when GA
+          # @public_api
           class Settings < Datadog::CI::Contrib::Settings
             option :enabled do |o|
               o.type :bool
@@ -22,6 +22,7 @@ class Settings < Datadog::CI::Contrib::Settings
               o.default { Datadog.configuration.service_without_fallback || Ext::SERVICE_NAME }
             end
 
+            # @deprecated Will be removed in 1.0
             option :operation_name do |o|
               o.type :string
               o.env Ext::ENV_OPERATION_NAME

lib/datadog/ci/contrib/rspec/configuration/settings.rb

@@ -9,7 +9,7 @@ module Contrib
       module RSpec
         module Configuration
           # Custom settings for the RSpec integration
-          # TODO: mark as `@public_api` when GA
+          # @public_api
           class Settings < Datadog::CI::Contrib::Settings
             option :enabled do |o|
               o.type :bool
@@ -22,6 +22,7 @@ class Settings < Datadog::CI::Contrib::Settings
               o.default { Datadog.configuration.service_without_fallback || Ext::SERVICE_NAME }
             end
 
+            # @deprecated Will be removed in 1.0
             option :operation_name do |o|
               o.type :string
               o.env Ext::ENV_OPERATION_NAME

lib/datadog/ci/contrib/settings.rb

@@ -10,6 +10,8 @@ class Settings
 
         option :enabled, default: true
         option :service_name
+
+        # @deprecated Will be removed in 1.0
         option :operation_name
 
         def configure(options = {})

lib/datadog/ci/ext/test.rb

@@ -4,6 +4,7 @@ module Datadog
   module CI
     module Ext
       # Defines constants for test tags
+      # @public_api
       module Test
         CONTEXT_ORIGIN = "ciapp-test"
 

yard/extensions.rb

@@ -2,27 +2,6 @@
 
 TOP_LEVEL_MODULE_FILE = "lib/datadog/ci.rb"
 
-# The top-level `Datadog` module gets its docstring overwritten by
-# on almost every file in the repo, due to comments at the top of the file
-# (e.g. '# typed: true' or from vendor files 'Copyright (c) 2001-2010 Not Datadog.')
-#
-# This module ensures that only the comment provided by 'lib/ddtrace.rb'
-# is used as documentation for the top-level `Datadog` module.
-#
-# For non-top-level documentation, this can be solved by removing duplicate module/class
-# documentation. But for top-level it's tricky, as it is common to leave general comments
-# and directives in the first lines of a file.
-module EnsureTopLevelModuleCommentConsistency
-  def register_docstring(object, *args)
-    if object.is_a?(YARD::CodeObjects::ModuleObject) && object.path == "Datadog" && parser.file != TOP_LEVEL_MODULE_FILE
-      super(object, nil)
-    else
-      super
-    end
-  end
-end
-YARD::Handlers::Base.prepend(EnsureTopLevelModuleCommentConsistency)
-
 # Sanity check to ensure we haven't renamed the top-level module definition file.
 YARD::Parser::SourceParser.before_parse_list do |files, _global_state|
   raise "Top-level module file not found: #{TOP_LEVEL_MODULE_FILE}. Has it been moved?" unless

yard/templates/default/docstring/html/deprecated.erb

@@ -0,0 +1 @@
+<div class="note deprecated"><strong>Deprecated <%= link_file('Deprecation.md', 'for removal') %>.</strong> <%= htmlify_line object.tag(:deprecated).text %></div>

yard/templates/default/docstring/setup.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# def init
+#   return if object.docstring.blank? && !object.has_tag?(:api)
+#   sections :index, [:private, :deprecated, :abstract, :todo, :note, :returns_void, :text], T('tags')
+# end
+
+def deprecated
+  return unless object.has_tag?(:deprecated)
+
+  erb(:deprecated)
+end