<page xmlns="http://projectmallard.org/1.0/"
      type="topic"
      id="gedit-plugin-code-comment">

  <info>
    <link type="guide" xref="gedit-plugin-guide#gedit-default-plugins"/>
    <desc>Comment-out or uncomment lines of code.</desc>
  </info>

  <title>Code Comment</title>

  <p>
    The purpose of the <app>Code Comment</app> plugin is to disable or re-enable
    a portion of code. It inserts or removes the characters used for comments,
    depending on the language or syntax of the file.
  </p>

  <p>
    First select some lines of code (or lines of text), then trigger the desired
    action (comment or uncomment) via one of these methods:
  </p>
  <list>
    <item><p>
        With the right-click menu in the main text area.
    </p></item>
    <item><p>
        With keyboard shortcuts: <keyseq><key>Ctrl</key><key>M</key></keyseq>
        for the comment action, and
        <keyseq><key>Ctrl</key><key>Shift</key><key>M</key></keyseq> for the
        uncomment action.
    </p></item>
  </list>

  <section>
    <title>Troubleshooting</title>
    <p>If it doesn't work:</p>
    <list>
      <item><p>
        Make sure that the plugin is enabled by going to the
        <gui>Preferences</gui> dialog.
      </p></item>
      <item><p>
        Check that the
        <link xref="gedit-syntax-highlighting">highlight mode</link>
        (the syntax) for the document is correctly set and is not “Plain Text”.
        For plain text documents, the code comment plugin doesn't know what
        characters to insert or remove.
      </p></item>
      <item><p>
        If it still doesn't work as intended, a more advanced technique is to
        look at the
        <link href="https://gedit-text-editor.org/developer-docs/libgedit-gtksourceview-300/lang-reference.html">language definition</link>
        files. From these files, the code comment plugin uses the
        <code>line-comment-start</code>, <code>block-comment-start</code> and
        <code>block-comment-end</code> metadata.
      </p></item>
      <!--
      <item><p>
        You can also launch <app>gedit</app> from a terminal to see if it prints
        relevant warning messages.
      </p></item>
      -->
    </list>
  </section>
</page>
