Module: ElasticGraph::SchemaDefinition::Mixins::HasDocumentation

Included in:
SchemaElements::Argument, SchemaElements::EnumType, SchemaElements::EnumValue, SchemaElements::Field, SchemaElements::ScalarType, SchemaElements::TypeWithSubfields, SchemaElements::UnionType
Defined in:
lib/elastic_graph/schema_definition/mixins/has_documentation.rb

Overview

Supports GraphQL documentation.

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#doc_comment ⇒ String?

Returns current documentation string for the schema element.

Returns:

  • (String, nil) —

    current documentation string for the schema element



17
18
19
 
# File 'lib/elastic_graph/schema_definition/mixins/has_documentation.rb', line 17

def doc_comment
  @doc_comment
end

Instance Method Details

#append_to_documentation(comment) ⇒ void

This method returns an undefined value.

Appends some additional documentation to the existing documentation string.

Parameters:

  • comment (String) —

    additional documentation



46
47
48
49
 
# File 'lib/elastic_graph/schema_definition/mixins/has_documentation.rb', line 46

def append_to_documentation(comment)
  new_documentation = doc_comment ? "#{doc_comment}\n\n#{comment}" : comment
  documentation(new_documentation)
end

#derived_documentation(intro, outro = nil) ⇒ String

Generates a documentation string that is derived from the schema elements existing documentation.

Parameters:

  • intro (String) —

    string that goes before the schema element’s existing documentation

  • outro (String, nil) (defaults to: nil) —

    string that goes after the schema element’s existing documentation

Returns:

  • (String) 


64
65
66
67
68
69
70
 
# File 'lib/elastic_graph/schema_definition/mixins/has_documentation.rb', line 64

def derived_documentation(intro, outro = nil)
  outro &&= "\n\n#{outro}."
  return "#{intro}.#{outro}" unless doc_comment

  quoted_doc = doc_comment.split("\n").map { |line| "> #{line}" }.join("\n")
  "#{intro}:\n\n#{quoted_doc}#{outro}"
end

#documentation(comment) ⇒ void

This method returns an undefined value.

Sets the documentation of the schema element.

Examples:

Define documentation on an object type and on a field

ElasticGraph.define_schema do |schema|
  schema.object_type "Campaign" do |t|
    t.documentation "A marketing campaign."

    t.field "id", "ID" do |f|
      f.documentation <<~EOS
        The identifier of the campaign.

        Note: this is randomly generated.
      EOS
    end
  end
end

Parameters:

  • comment (String) —

    the documentation string



38
39
40
 
# File 'lib/elastic_graph/schema_definition/mixins/has_documentation.rb', line 38

def documentation(comment)
  self.doc_comment = comment
end

#formatted_documentation ⇒ String

Formats the documentation using GraphQL SDL syntax.

Returns:

  • (String) —

    formatted documentation string



54
55
56
57
 
# File 'lib/elastic_graph/schema_definition/mixins/has_documentation.rb', line 54

def formatted_documentation
  return nil unless (comment = doc_comment)
  %("""\n#{comment.chomp}\n"""\n)
end