Merge branch 'adam-separate-slash-commands' into 'master'

Display slash commands outcome when previewing Markdown

Closes #21531

See merge request !10054

app/assets/javascripts/preview_markdown.js

@@ -2,8 +2,9 @@
 
 // MarkdownPreview
 //
-// Handles toggling the "Write" and "Preview" tab clicks, rendering the preview,
-// and showing a warning when more than `x` users are referenced.
+// Handles toggling the "Write" and "Preview" tab clicks, rendering the preview
+// (including the explanation of slash commands), and showing a warning when
+// more than `x` users are referenced.
 //
 (function () {
   var lastTextareaPreviewed;
@@ -17,32 +18,45 @@
 
     // Minimum number of users referenced before triggering a warning
     MarkdownPreview.prototype.referenceThreshold = 10;
+    MarkdownPreview.prototype.emptyMessage = 'Nothing to preview.';
 
     MarkdownPreview.prototype.ajaxCache = {};
 
     MarkdownPreview.prototype.showPreview = function ($form) {
       var mdText;
       var preview = $form.find('.js-md-preview');
+      var url = preview.data('url');
       if (preview.hasClass('md-preview-loading')) {
         return;
       }
       mdText = $form.find('textarea.markdown-area').val();
 
       if (mdText.trim().length === 0) {
-        preview.text('Nothing to preview.');
+        preview.text(this.emptyMessage);
         this.hideReferencedUsers($form);
       } else {
         preview.addClass('md-preview-loading').text('Loading...');
-        this.fetchMarkdownPreview(mdText, (function (response) {
-          preview.removeClass('md-preview-loading').html(response.body);
+        this.fetchMarkdownPreview(mdText, url, (function (response) {
+          var body;
+          if (response.body.length > 0) {
+            body = response.body;
+          } else {
+            body = this.emptyMessage;
+          }
+
+          preview.removeClass('md-preview-loading').html(body);
           preview.renderGFM();
           this.renderReferencedUsers(response.references.users, $form);
+
+          if (response.references.commands) {
+            this.renderReferencedCommands(response.references.commands, $form);
+          }
         }).bind(this));
       }
     };
 
-    MarkdownPreview.prototype.fetchMarkdownPreview = function (text, success) {
-      if (!window.preview_markdown_path) {
+    MarkdownPreview.prototype.fetchMarkdownPreview = function (text, url, success) {
+      if (!url) {
         return;
       }
       if (text === this.ajaxCache.text) {
@@ -51,7 +65,7 @@
       }
       $.ajax({
         type: 'POST',
-        url: window.preview_markdown_path,
+        url: url,
         data: {
           text: text
         },
@@ -83,6 +97,22 @@
       }
     };
 
+    MarkdownPreview.prototype.hideReferencedCommands = function ($form) {
+      $form.find('.referenced-commands').hide();
+    };
+
+    MarkdownPreview.prototype.renderReferencedCommands = function (commands, $form) {
+      var referencedCommands;
+      referencedCommands = $form.find('.referenced-commands');
+      if (commands.length > 0) {
+        referencedCommands.html(commands);
+        referencedCommands.show();
+      } else {
+        referencedCommands.html('');
+        referencedCommands.hide();
+      }
+    };
+
     return MarkdownPreview;
   }());
 
@@ -137,6 +167,8 @@
     $form.find('.md-write-holder').show();
     $form.find('textarea.markdown-area').focus();
     $form.find('.md-preview-holder').hide();
+
+    markdownPreview.hideReferencedCommands($form);
   });
 
   $(document).on('markdown-preview:toggle', function (e, keyboardEvent) {

app/controllers/concerns/markdown_preview.rb

-module MarkdownPreview
-  private
-
-  def render_markdown_preview(text, markdown_context = {})
-    render json: {
-      body: view_context.markdown(text, markdown_context),
-      references: {
-        users: preview_referenced_users(text)
-      }
-    }
-  end
-
-  def preview_referenced_users(text)
-    extractor = Gitlab::ReferenceExtractor.new(@project, current_user)
-    extractor.analyze(text, author: current_user)
-
-    extractor.users.map(&:username)
-  end
-end

app/controllers/projects/wikis_controller.rb

 class Projects::WikisController < Projects::ApplicationController
-  include MarkdownPreview
-
   before_action :authorize_read_wiki!
   before_action :authorize_create_wiki!, only: [:edit, :create, :history]
   before_action :authorize_admin_wiki!, only: :destroy
@@ -97,9 +95,14 @@ class Projects::WikisController < Projects::ApplicationController
   end
 
   def preview_markdown
-    context = { pipeline: :wiki, project_wiki: @project_wiki, page_slug: params[:id] }
-
-    render_markdown_preview(params[:text], context)
+    result = PreviewMarkdownService.new(@project, current_user, params).execute
+
+    render json: {
+      body: view_context.markdown(result[:text], pipeline: :wiki, project_wiki: @project_wiki, page_slug: params[:id]),
+      references: {
+        users: result[:users]
+      }
+    }
   end
 
   private

app/controllers/projects_controller.rb

 class ProjectsController < Projects::ApplicationController
   include IssuableCollections
   include ExtractsPath
-  include MarkdownPreview
 
   before_action :authenticate_user!, except: [:index, :show, :activity, :refs]
   before_action :project, except: [:index, :new, :create]
@@ -240,7 +239,15 @@ class ProjectsController < Projects::ApplicationController
   end
 
   def preview_markdown
-    render_markdown_preview(params[:text])
+    result = PreviewMarkdownService.new(@project, current_user, params).execute
+
+    render json: {
+      body: view_context.markdown(result[:text]),
+      references: {
+        users: result[:users],
+        commands: view_context.markdown(result[:commands])
+      }
+    }
   end
 
   private

app/controllers/snippets_controller.rb

@@ -3,7 +3,6 @@ class SnippetsController < ApplicationController
   include ToggleAwardEmoji
   include SpammableActions
   include SnippetsActions
-  include MarkdownPreview
   include RendersBlob
 
   before_action :snippet, only: [:show, :edit, :destroy, :update, :raw]
@@ -90,7 +89,14 @@ class SnippetsController < ApplicationController
   end
 
   def preview_markdown
-    render_markdown_preview(params[:text], skip_project_check: true)
+    result = PreviewMarkdownService.new(@project, current_user, params).execute
+
+    render json: {
+      body: view_context.markdown(result[:text], skip_project_check: true),
+      references: {
+        users: result[:users]
+      }
+    }
   end
 
   protected

app/helpers/gitlab_routing_helper.rb

@@ -122,6 +122,10 @@ module GitlabRoutingHelper
     namespace_project_snippet_url(entity.project.namespace, entity.project, entity, *args)
   end
 
+  def preview_markdown_path(project, *args)
+    preview_markdown_namespace_project_path(project.namespace, project, *args)
+  end
+
   def toggle_subscription_path(entity, *args)
     if entity.is_a?(Issue)
       toggle_subscription_namespace_project_issue_path(entity.project.namespace, entity.project, entity)

app/services/preview_markdown_service.rb

+class PreviewMarkdownService < BaseService
+  def execute
+    text, commands = explain_slash_commands(params[:text])
+    users = find_user_references(text)
+
+    success(
+      text: text,
+      users: users,
+      commands: commands.join(' ')
+    )
+  end
+
+  private
+
+  def explain_slash_commands(text)
+    return text, [] unless %w(Issue MergeRequest).include?(commands_target_type)
+
+    slash_commands_service = SlashCommands::InterpretService.new(project, current_user)
+    slash_commands_service.explain(text, find_commands_target)
+  end
+
+  def find_user_references(text)
+    extractor = Gitlab::ReferenceExtractor.new(project, current_user)
+    extractor.analyze(text, author: current_user)
+    extractor.users.map(&:username)
+  end
+
+  def find_commands_target
+    if commands_target_id.present?
+      finder = commands_target_type == 'Issue' ? IssuesFinder : MergeRequestsFinder
+      finder.new(current_user, project_id: project.id).find(commands_target_id)
+    else
+      collection = commands_target_type == 'Issue' ? project.issues : project.merge_requests
+      collection.build
+    end
+  end
+
+  def commands_target_type
+    params[:slash_commands_target_type]
+  end
+
+  def commands_target_id
+    params[:slash_commands_target_id]
+  end
+end

app/views/groups/milestones/new.html.haml

@@ -26,7 +26,7 @@
       .form-group.milestone-description
         = f.label :description, "Description", class: "control-label"
         .col-sm-10
-          = render layout: 'projects/md_preview', locals: { preview_class: "md-preview" } do
+          = render layout: 'projects/md_preview', locals: { url: '' } do
             = render 'projects/zen', f: f, attr: :description, classes: 'note-textarea', placeholder: 'Write milestone description...'
             .clearfix
             .error-alert

app/views/layouts/project.html.haml

@@ -5,14 +5,9 @@
 
 - content_for :project_javascripts do
   - project = @target_project || @project
-  - if @project_wiki && @page
-    - preview_markdown_path = namespace_project_wiki_preview_markdown_path(project.namespace, project, @page.slug)
-  - else
-    - preview_markdown_path = preview_markdown_namespace_project_path(project.namespace, project)
   - if current_user
     :javascript
       window.uploads_path = "#{namespace_project_uploads_path project.namespace,project}";
-      window.preview_markdown_path = "#{preview_markdown_path}";
 
 - content_for :header_content do
   .js-dropdown-menu-projects

app/views/projects/_md_preview.html.haml

+- referenced_users = local_assigns.fetch(:referenced_users, nil)
+
 .md-area
   .md-header
     %ul.nav-links.clearfix
@@ -28,9 +30,10 @@
 
   .md-write-holder
     = yield
-  .md.md-preview-holder.js-md-preview.hide{ class: (preview_class if defined?(preview_class)) }
+  .md.md-preview-holder.js-md-preview.hide.md-preview{ data: { url: url } }
+  .referenced-commands.hide
 
-  - if defined?(referenced_users) && referenced_users
+  - if referenced_users
     .referenced-users.hide
       %span
         = icon("exclamation-triangle")

app/views/projects/milestones/_form.html.haml

@@ -9,7 +9,7 @@
       .form-group.milestone-description
         = f.label :description, "Description", class: "control-label"
         .col-sm-10
-          = render layout: 'projects/md_preview', locals: { preview_class: "md-preview" } do
+          = render layout: 'projects/md_preview', locals: { url: preview_markdown_path(@project) } do
             = render 'projects/zen', f: f, attr: :description, classes: 'note-textarea', placeholder: 'Write milestone description...'
             = render 'projects/notes/hints'
           .clearfix

app/views/projects/notes/_edit_form.html.haml

@@ -2,7 +2,7 @@
   = form_tag '#', method: :put, class: 'edit-note common-note-form js-quick-submit' do
     = hidden_field_tag :target_id, '', class: 'js-form-target-id'
     = hidden_field_tag :target_type, '', class: 'js-form-target-type'
-    = render layout: 'projects/md_preview', locals: { preview_class: 'md-preview', referenced_users: true } do
+    = render layout: 'projects/md_preview', locals: { url: preview_markdown_path(project), referenced_users: true } do
       = render 'projects/zen', attr: 'note[note]', classes: 'note-textarea js-note-text js-task-list-field', placeholder: "Write a comment or drag your files here..."
       = render 'projects/notes/hints'
 

app/views/projects/notes/_form.html.haml

 - supports_slash_commands = note_supports_slash_commands?(@note)
+- if supports_slash_commands
+  - preview_url = preview_markdown_path(@project, slash_commands_target_type: @note.noteable_type, slash_commands_target_id: @note.noteable_id)
+- else
+  - preview_url = preview_markdown_path(@project)
 
 = form_for [@project.namespace.becomes(Namespace), @project, @note], remote: true, html: { :'data-type' => 'json', multipart: true, id: nil, class: "new-note js-new-note-form js-quick-submit common-note-form", "data-noteable-iid" => @note.noteable.try(:iid), }, authenticity_token: true do |f|
   = hidden_field_tag :view, diff_view
@@ -18,7 +22,7 @@
   -# DiffNote
   = f.hidden_field :position
 
-  = render layout: 'projects/md_preview', locals: { preview_class: "md-preview", referenced_users: true } do
+  = render layout: 'projects/md_preview', locals: { url: preview_url, referenced_users: true } do
     = render 'projects/zen', f: f,
       attr: :note,
       classes: 'note-textarea js-note-text',

app/views/projects/notes/_notes_with_form.html.haml

 %ul#notes-list.notes.main-notes-list.timeline
   = render "shared/notes/notes"
 
-= render 'projects/notes/edit_form'
+= render 'projects/notes/edit_form', project: @project
 
 %ul.notes.notes-form.timeline
   %li.timeline-entry

app/views/projects/releases/edit.html.haml

@@ -11,7 +11,7 @@
 
 
   = form_for(@release, method: :put, url: namespace_project_tag_release_path(@project.namespace, @project, @tag.name), html: { class: 'form-horizontal common-note-form release-form js-quick-submit' }) do |f|
-    = render layout: 'projects/md_preview', locals: { preview_class: "md-preview", referenced_users: true } do
+    = render layout: 'projects/md_preview', locals: { url: preview_markdown_path(@project), referenced_users: true } do
       = render 'projects/zen', f: f, attr: :description, classes: 'note-textarea', placeholder: "Write your release notes or drag files here..."
       = render 'projects/notes/hints'
     .error-alert

app/views/projects/tags/new.html.haml

@@ -28,7 +28,7 @@
   .form-group
     = label_tag :release_description, 'Release notes', class: 'control-label'
     .col-sm-10
-      = render layout: 'projects/md_preview', locals: { preview_class: "md-preview", referenced_users: true } do
+      = render layout: 'projects/md_preview', locals: { url: preview_markdown_path(@project), referenced_users: true } do
         = render 'projects/zen', attr: :release_description, classes: 'note-textarea', placeholder: "Write your release notes or drag files here..."
         = render 'projects/notes/hints'
       .help-block Optionally, add release notes to the tag. They will be stored in the GitLab database and displayed on the tags page.

app/views/projects/wikis/_form.html.haml

@@ -12,7 +12,7 @@
   .form-group
     = f.label :content, class: 'control-label'
     .col-sm-10
-      = render layout: 'projects/md_preview', locals: { preview_class: "md-preview" } do
+      = render layout: 'projects/md_preview', locals: { url: namespace_project_wiki_preview_markdown_path(@project.namespace, @project, @page.slug) } do
         = render 'projects/zen', f: f, attr: :content, classes: 'note-textarea', placeholder: 'Write your content or drag files here...'
         = render 'projects/notes/hints'
 

app/views/shared/issuable/_form.html.haml

@@ -17,7 +17,7 @@
   = render 'shared/issuable/form/template_selector', issuable: issuable
   = render 'shared/issuable/form/title', issuable: issuable, form: form, has_wip_commits: commits && commits.detect(&:work_in_progress?)
 
-= render 'shared/issuable/form/description', issuable: issuable, form: form
+= render 'shared/issuable/form/description', issuable: issuable, form: form, project: project
 
 - if issuable.respond_to?(:confidential)
   .form-group

app/views/shared/issuable/form/_description.html.haml

+- project = local_assigns.fetch(:project)
 - issuable = local_assigns.fetch(:issuable)
 - form = local_assigns.fetch(:form)
+- supports_slash_commands = issuable.new_record?
+
+- if supports_slash_commands
+  - preview_url = preview_markdown_path(project, slash_commands_target_type: issuable.class.name)
+- else
+  - preview_url = preview_markdown_path(project)
 
 .form-group.detail-page-description
   = form.label :description, 'Description', class: 'control-label'
   .col-sm-10
 
-    = render layout: 'projects/md_preview', locals: { preview_class: "md-preview", referenced_users: true } do
+    = render layout: 'projects/md_preview', locals: { url: preview_url, referenced_users: true } do
       = render 'projects/zen', f: form, attr: :description,
                                classes: 'note-textarea',
                                placeholder: "Write a comment or drag your files here...",
-                               supports_slash_commands: !issuable.persisted?
-      = render 'projects/notes/hints', supports_slash_commands: !issuable.persisted?
+                               supports_slash_commands: supports_slash_commands
+      = render 'projects/notes/hints', supports_slash_commands: supports_slash_commands
       .clearfix
       .error-alert

changelogs/unreleased/preview-separate-slash-commands.yml

+---
+title: Display slash commands outcome when previewing Markdown
+merge_request: 10054
+author: Rares Sfirlogea

lib/gitlab/slash_commands/command_definition.rb

 module Gitlab
   module SlashCommands
     class CommandDefinition
-      attr_accessor :name, :aliases, :description, :params, :condition_block, :action_block
+      attr_accessor :name, :aliases, :description, :explanation, :params,
+        :condition_block, :parse_params_block, :action_block
 
       def initialize(name, attributes = {})
         @name = name
 
-        @aliases         = attributes[:aliases] || []
-        @description     = attributes[:description] || ''
-        @params          = attributes[:params] || []
+        @aliases = attributes[:aliases] || []
+        @description = attributes[:description] || ''
+        @explanation = attributes[:explanation] || ''
+        @params = attributes[:params] || []
         @condition_block = attributes[:condition_block]
-        @action_block    = attributes[:action_block]
+        @parse_params_block = attributes[:parse_params_block]
+        @action_block = attributes[:action_block]
       end
 
       def all_names
@@ -28,14 +31,20 @@ module Gitlab
         context.instance_exec(&condition_block)
       end
 
+      def explain(context, opts, arg)
+        return unless available?(opts)
+
+        if explanation.respond_to?(:call)
+          execute_block(explanation, context, arg)
+        else
+          explanation
+        end
+      end
+
       def execute(context, opts, arg)
         return if noop? || !available?(opts)
 
-        if arg.present?
-          context.instance_exec(arg, &action_block)
-        elsif action_block.arity == 0
-          context.instance_exec(&action_block)
-        end
+        execute_block(action_block, context, arg)
       end
 
       def to_h(opts)
@@ -52,6 +61,23 @@ module Gitlab
           params: params
         }
       end
+
+      private
+
+      def execute_block(block, context, arg)
+        if arg.present?
+          parsed = parse_params(arg, context)
+          context.instance_exec(parsed, &block)
+        elsif block.arity == 0
+          context.instance_exec(&block)
+        end
+      end
+
+      def parse_params(arg, context)
+        return arg unless parse_params_block
+
+        context.instance_exec(arg, &parse_params_block)
+      end
     end
   end
 end

lib/gitlab/slash_commands/dsl.rb

@@ -44,6 +44,22 @@ module Gitlab
           @params = params
         end
 
+        # Allows to give an explanation of what the command will do when
+        # executed. This explanation is shown when rendering the Markdown
+        # preview.
+        #
+        # Example:
+        #
+        #   explanation do |arguments|
+        #     "Adds label(s) #{arguments.join(' ')}"
+        #   end
+        #   command :command_key do |arguments|
+        #     # Awesome code block
+        #   end
+        def explanation(text = '', &block)
+          @explanation = block_given? ? block : text
+        end
+
         # Allows to define conditions that must be met in order for the command
         # to be returned by `.command_names` & `.command_definitions`.
         # It accepts a block that will be evaluated with the context given to
@@ -61,6 +77,24 @@ module Gitlab
           @condition_block = block
         end
 
+        # Allows to perform initial parsing of parameters. The result is passed
+        # both to `command` and `explanation` blocks, instead of the raw
+        # parameters.
+        # It accepts a block that will be evaluated with the context given to
+        # `CommandDefintion#to_h`.
+        #
+        # Example:
+        #
+        #   parse_params do |raw|
+        #     raw.strip
+        #   end
+        #   command :command_key do |parsed|
+        #     # Awesome code block
+        #   end
+        def parse_params(&block)
+          @parse_params_block = block
+        end
+
         # Registers a new command which is recognizeable from body of email or
         # comment.
         # It accepts aliases and takes a block.
@@ -75,11 +109,13 @@ module Gitlab
 
           definition = CommandDefinition.new(
             name,
-            aliases:          aliases,
-            description:      @description,
-            params:           @params,
-            condition_block:  @condition_block,
-            action_block:     block
+            aliases: aliases,
+            description: @description,
+            explanation: @explanation,
+            params: @params,
+            condition_block: @condition_block,
+            parse_params_block: @parse_params_block,
+            action_block: block
           )
 
           self.command_definitions << definition
@@ -89,8 +125,14 @@ module Gitlab
           end
 
           @description = nil
+          @explanation = nil
           @params = nil
           @condition_block = nil
+          @parse_params_block = nil
+        end
+
+        def definition_by_name(name)
+          command_definitions_by_name[name.to_sym]
         end
       end
     end

spec/lib/gitlab/slash_commands/command_definition_spec.rb

@@ -167,6 +167,58 @@ describe Gitlab::SlashCommands::CommandDefinition do
             end
           end
         end
+
+        context 'when the command defines parse_params block' do
+          before do
+            subject.parse_params_block = ->(raw) { raw.strip }
+            subject.action_block = ->(parsed) { self.received_arg = parsed }
+          end
+
+          it 'executes the command passing the parsed param' do
+            subject.execute(context, {}, 'something   ')
+
+            expect(context.received_arg).to eq('something')
+          end
+        end
+      end
+    end
+  end
+
+  describe '#explain' do
+    context 'when the command is not available' do
+      before do
+        subject.condition_block = proc { false }
+        subject.explanation = 'Explanation'
+      end
+
+      it 'returns nil' do
+        result = subject.explain({}, {}, nil)
+
+        expect(result).to be_nil
+      end
+    end
+
+    context 'when the explanation is a static string' do
+      before do
+        subject.explanation = 'Explanation'
+      end
+
+      it 'returns this static string' do
+        result = subject.explain({}, {}, nil)
+
+        expect(result).to eq 'Explanation'
+      end
+    end
+
+    context 'when the explanation is dynamic' do
+      before do
+        subject.explanation = proc { |arg| "Dynamic #{arg}" }
+      end
+
+      it 'invokes the proc' do
+        result = subject.explain({}, {}, 'explanation')
+
+        expect(result).to eq 'Dynamic explanation'
       end
     end
   end

spec/lib/gitlab/slash_commands/dsl_spec.rb

@@ -11,67 +11,99 @@ describe Gitlab::SlashCommands::Dsl do
       end
 
       params 'The first argument'
-      command :one_arg, :once, :first do |arg1|
-        arg1
+      explanation 'Static explanation'
+      command :explanation_with_aliases, :once, :first do |arg|
+        arg
       end
 
       desc do
         "A dynamic description for #{noteable.upcase}"
       end
       params 'The first argument', 'The second argument'
-      command :two_args do |arg1, arg2|
-        [arg1, arg2]
+      command :dynamic_description do |args|
+        args.split
       end
 
       command :cc
 
+      explanation do |arg|
+        "Action does something with #{arg}"
+      end
       condition do
         project == 'foo'
       end
       command :cond_action do |arg|
         arg
       end
+
+      parse_params do |raw_arg|
+        raw_arg.strip
+      end
+      command :with_params_parsing do |parsed|
+        parsed
+      end
     end
   end
 
   describe '.command_definitions' do
     it 'returns an array with commands definitions' do
-      no_args_def, one_arg_def, two_args_def, cc_def, cond_action_def = DummyClass.command_definitions
+      no_args_def, explanation_with_aliases_def, dynamic_description_def,
+      cc_def, cond_action_def, with_params_parsing_def =
+        DummyClass.command_definitions
 
       expect(no_args_def.name).to eq(:no_args)
       expect(no_args_def.aliases).to eq([:none])
       expect(no_args_def.description).to eq('A command with no args')
+      expect(no_args_def.explanation).to eq('')
       expect(no_args_def.params).to eq([])
       expect(no_args_def.condition_block).to be_nil
       expect(no_args_def.action_block).to be_a_kind_of(Proc)
+      expect(no_args_def.parse_params_block).to be_nil
 
-      expect(one_arg_def.name).to eq(:one_arg)
-      expect(one_arg_def.aliases).to eq([:once, :first])
-      expect(one_arg_def.description).to eq('')
-      expect(one_arg_def.params).to eq(['The first argument'])
-      expect(one_arg_def.condition_block).to be_nil
-      expect(one_arg_def.action_block).to be_a_kind_of(Proc)
+      expect(explanation_with_aliases_def.name).to eq(:explanation_with_aliases)
+      expect(explanation_with_aliases_def.aliases).to eq([:once, :first])
+      expect(explanation_with_aliases_def.description).to eq('')
+      expect(explanation_with_aliases_def.explanation).to eq('Static explanation')
+      expect(explanation_with_aliases_def.params).to eq(['The first argument'])
+      expect(explanation_with_aliases_def.condition_block).to be_nil
+      expect(explanation_with_aliases_def.action_block).to be_a_kind_of(Proc)
+      expect(explanation_with_aliases_def.parse_params_block).to be_nil
 
-      expect(two_args_def.name).to eq(:two_args)
-      expect(two_args_def.aliases).to eq([])
-      expect(two_args_def.to_h(noteable: "issue")[:description]).to eq('A dynamic description for ISSUE')
-      expect(two_args_def.params).to eq(['The first argument', 'The second argument'])
-      expect(two_args_def.condition_block).to be_nil
-      expect(two_args_def.action_block).to be_a_kind_of(Proc)
+      expect(dynamic_description_def.name).to eq(:dynamic_description)
+      expect(dynamic_description_def.aliases).to eq([])
+      expect(dynamic_description_def.to_h(noteable: 'issue')[:description]).to eq('A dynamic description for ISSUE')
+      expect(dynamic_description_def.explanation).to eq('')
+      expect(dynamic_description_def.params).to eq(['The first argument', 'The second argument'])
+      expect(dynamic_description_def.condition_block).to be_nil
+      expect(dynamic_description_def.action_block).to be_a_kind_of(Proc)
+      expect(dynamic_description_def.parse_params_block).to be_nil
 
       expect(cc_def.name).to eq(:cc)
       expect(cc_def.aliases).to eq([])
       expect(cc_def.description).to eq('')
+      expect(cc_def.explanation).to eq('')
       expect(cc_def.params).to eq([])
       expect(cc_def.condition_block).to be_nil
       expect(cc_def.action_block).to be_nil
+      expect(cc_def.parse_params_block).to be_nil
 
       expect(cond_action_def.name).to eq(:cond_action)
       expect(cond_action_def.aliases).to eq([])
       expect(cond_action_def.description).to eq('')
+      expect(cond_action_def.explanation).to be_a_kind_of(Proc)
       expect(cond_action_def.params).to eq([])
       expect(cond_action_def.condition_block).to be_a_kind_of(Proc)
       expect(cond_action_def.action_block).to be_a_kind_of(Proc)
+      expect(cond_action_def.parse_params_block).to be_nil
+
+      expect(with_params_parsing_def.name).to eq(:with_params_parsing)
+      expect(with_params_parsing_def.aliases).to eq([])
+      expect(with_params_parsing_def.description).to eq('')
+      expect(with_params_parsing_def.explanation).to eq('')
+      expect(with_params_parsing_def.params).to eq([])
+      expect(with_params_parsing_def.condition_block).to be_nil
+      expect(with_params_parsing_def.action_block).to be_a_kind_of(Proc)
+      expect(with_params_parsing_def.parse_params_block).to be_a_kind_of(Proc)
     end
   end
 end

spec/services/preview_markdown_service_spec.rb

+require 'spec_helper'
+
+describe PreviewMarkdownService do
+  let(:user) { create(:user) }
+  let(:project) { create(:empty_project) }
+
+  before do
+    project.add_developer(user)
+  end
+
+  describe 'user references' do
+    let(:params) { { text: "Take a look #{user.to_reference}" } }
+    let(:service) { described_class.new(project, user, params) }
+
+    it 'returns users referenced in text' do
+      result = service.execute
+
+      expect(result[:users]).to eq [user.username]
+    end
+  end
+
+  context 'new note with slash commands' do
+    let(:issue) { create(:issue, project: project) }
+    let(:params) do
+      {
+        text: "Please do it\n/assign #{user.to_reference}",
+        slash_commands_target_type: 'Issue',
+        slash_commands_target_id: issue.id
+      }
+    end
+    let(:service) { described_class.new(project, user, params) }
+
+    it 'removes slash commands from text' do
+      result = service.execute
+
+      expect(result[:text]).to eq 'Please do it'
+    end
+
+    it 'explains slash commands effect' do
+      result = service.execute
+
+      expect(result[:commands]).to eq "Assigns #{user.to_reference}."
+    end
+  end
+
+  context 'merge request description' do
+    let(:params) do
+      {
+        text: "My work\n/estimate 2y",
+        slash_commands_target_type: 'MergeRequest'
+      }
+    end
+    let(:service) { described_class.new(project, user, params) }
+
+    it 'removes slash commands from text' do
+      result = service.execute
+
+      expect(result[:text]).to eq 'My work'
+    end
+
+    it 'explains slash commands effect' do
+      result = service.execute
+
+      expect(result[:commands]).to eq 'Sets time estimate to 2y.'
+    end    
+  end
+end

spec/services/slash_commands/interpret_service_spec.rb

@@ -798,4 +798,211 @@ describe SlashCommands::InterpretService, services: true do
       end
     end
   end
+
+  describe '#explain' do
+    let(:service) { described_class.new(project, developer) }
+    let(:merge_request) { create(:merge_request, source_project: project) }
+
+    describe 'close command' do
+      let(:content) { '/close' }
+
+      it 'includes issuable name' do
+        _, explanations = service.explain(content, issue)
+
+        expect(explanations).to eq(['Closes this issue.'])
+      end
+    end
+
+    describe 'reopen command' do
+      let(:content) { '/reopen' }
+      let(:merge_request) { create(:merge_request, :closed, source_project: project) }
+
+      it 'includes issuable name' do
+        _, explanations = service.explain(content, merge_request)
+
+        expect(explanations).to eq(['Reopens this merge request.'])
+      end
+    end
+
+    describe 'title command' do
+      let(:content) { '/title This is new title' }
+
+      it 'includes new title' do
+        _, explanations = service.explain(content, issue)
+
+        expect(explanations).to eq(['Changes the title to "This is new title".'])
+      end
+    end
+
+    describe 'assign command' do
+      let(:content) { "/assign @#{developer.username} do it!" }
+
+      it 'includes only the user reference' do
+        _, explanations = service.explain(content, merge_request)
+
+        expect(explanations).to eq(["Assigns @#{developer.username}."])
+      end
+    end
+
+    describe 'unassign command' do
+      let(:content) { '/unassign' }
+      let(:issue) { create(:issue, project: project, assignee: developer) }
+
+      it 'includes current assignee reference' do
+        _, explanations = service.explain(content, issue)
+
+        expect(explanations).to eq(["Removes assignee @#{developer.username}."])
+      end
+    end
+
+    describe 'milestone command' do
+      let(:content) { '/milestone %wrong-milestone' }
+      let!(:milestone) { create(:milestone, project: project, title: '9.10') }
+
+      it 'is empty when milestone reference is wrong' do
+        _, explanations = service.explain(content, issue)
+
+        expect(explanations).to eq([])
+      end
+    end
+
+    describe 'remove milestone command' do
+      let(:content) { '/remove_milestone' }
+      let(:merge_request) { create(:merge_request, source_project: project, milestone: milestone) }
+
+      it 'includes current milestone name' do
+        _, explanations = service.explain(content, merge_request)
+
+        expect(explanations).to eq(['Removes %"9.10" milestone.'])
+      end
+    end
+
+    describe 'label command' do
+      let(:content) { '/label ~missing' }
+      let!(:label) { create(:label, project: project) }
+
+      it 'is empty when there are no correct labels' do
+        _, explanations = service.explain(content, issue)
+
+        expect(explanations).to eq([])
+      end
+    end
+
+    describe 'unlabel command' do
+      let(:content) { '/unlabel' }
+
+      it 'says all labels if no parameter provided' do
+        merge_request.update!(label_ids: [bug.id])
+        _, explanations = service.explain(content, merge_request)
+
+        expect(explanations).to eq(['Removes all labels.'])
+      end
+    end
+
+    describe 'relabel command' do
+      let(:content) { '/relabel Bug' }
+      let!(:bug) { create(:label, project: project, title: 'Bug') }
+      let(:feature) { create(:label, project: project, title: 'Feature') }
+
+      it 'includes label name' do
+        issue.update!(label_ids: [feature.id])
+        _, explanations = service.explain(content, issue)
+
+        expect(explanations).to eq(["Replaces all labels with ~#{bug.id} label."])
+      end
+    end
+
+    describe 'subscribe command' do
+      let(:content) { '/subscribe' }
+
+      it 'includes issuable name' do
+        _, explanations = service.explain(content, issue)
+
+        expect(explanations).to eq(['Subscribes to this issue.'])
+      end
+    end
+
+    describe 'unsubscribe command' do
+      let(:content) { '/unsubscribe' }
+
+      it 'includes issuable name' do
+        merge_request.subscribe(developer, project)
+        _, explanations = service.explain(content, merge_request)
+
+        expect(explanations).to eq(['Unsubscribes from this merge request.'])
+      end
+    end
+
+    describe 'due command' do
+      let(:content) { '/due April 1st 2016' }
+
+      it 'includes the date' do
+        _, explanations = service.explain(content, issue)
+
+        expect(explanations).to eq(['Sets the due date to Apr 1, 2016.'])
+      end
+    end
+
+    describe 'wip command' do
+      let(:content) { '/wip' }
+
+      it 'includes the new status' do
+        _, explanations = service.explain(content, merge_request)
+
+        expect(explanations).to eq(['Marks this merge request as Work In Progress.'])
+      end
+    end
+
+    describe 'award command' do
+      let(:content) { '/award :confetti_ball: ' }
+
+      it 'includes the emoji' do
+        _, explanations = service.explain(content, issue)
+
+        expect(explanations).to eq(['Toggles :confetti_ball: emoji award.'])
+      end
+    end
+
+    describe 'estimate command' do
+      let(:content) { '/estimate 79d' }
+
+      it 'includes the formatted duration' do
+        _, explanations = service.explain(content, merge_request)
+
+        expect(explanations).to eq(['Sets time estimate to 3mo 3w 4d.'])
+      end
+    end
+
+    describe 'spend command' do
+      let(:content) { '/spend -120m' }
+
+      it 'includes the formatted duration and proper verb' do
+        _, explanations = service.explain(content, issue)
+
+        expect(explanations).to eq(['Substracts 2h spent time.'])
+      end
+    end
+
+    describe 'target branch command' do
+      let(:content) { '/target_branch my-feature ' }
+
+      it 'includes the branch name' do
+        _, explanations = service.explain(content, merge_request)
+
+        expect(explanations).to eq(['Sets target branch to my-feature.'])
+      end
+    end
+
+    describe 'board move command' do
+      let(:content) { '/board_move ~bug' }
+      let!(:bug) { create(:label, project: project, title: 'bug') }
+      let!(:board) { create(:board, project: project) }
+
+      it 'includes the label name' do
+        _, explanations = service.explain(content, issue)
+
+        expect(explanations).to eq(["Moves issue to ~#{bug.id} column in the board."])
+      end
+    end
+  end
 end

spec/support/features/issuable_slash_commands_shared_examples.rb

@@ -257,4 +257,19 @@ shared_examples 'issuable record that supports slash commands in its description
       end
     end
   end
+
+  describe "preview of note on #{issuable_type}" do
+    it 'removes slash commands from note and explains them' do
+      visit public_send("namespace_project_#{issuable_type}_path", project.namespace, project, issuable)
+
+      page.within('.js-main-target-form') do
+        fill_in 'note[note]', with: "Awesome!\n/assign @bob "
+        click_on 'Preview'
+
+        expect(page).to have_content 'Awesome!'
+        expect(page).not_to have_content '/assign @bob'
+        expect(page).to have_content 'Assigns @bob.'
+      end
+    end
+  end
 end