Scope determines what class Natural Docs thinks a comment is part of.  So if you were to write "Function: MyFunction", is MyFunction global or part of a class?  It behaves somewhat differently based on whether you have full language support or basic language support, though even if your language has full support the other rules will still apply to text files and standalone comments.

If your programming language has basic support that means Natural Docs doesn't have a parser written specifically for that language and can't interpret its code.  The scope is instead determined by the sequence of Natural Docs comments and follows these rules:

• Any comment that appears after a Class comment (or anything that says Starts Scope) is part of that class.

• Any comment that appears after a Section comment (or anything that says Ends Scope) is global again.

• Any File comment (or anything that says Always Global) is global no matter what and doesn't affect any other comments.

If you document everything this should just work without you worrying about it.  For example:

// Class: MyClass
public class MyClass
   {
   // Function: MyFunction
   public void MyFunction ()
      { ... }

   // Function: MyFunction2
   public void MyFunction2 ()
      { ... }
   }

// Class: AnotherClass
public class AnotherClass
   {
   // Function: AnotherFunction
   public void AnotherFunction ()
      { ... }
   }

The comment for MyClass starts the scope just like the actual class does, so MyFunction and MyFunction2 are seen as part of it.  The comment for AnotherClass changes the scope so AnotherFunction is part of that one instead.  As long as everything is documented it should just work.

However, if you didn't document AnotherClass Natural Docs would not know the scope changed and so AnotherFunction would be interpreted as part of MyClass.  If you didn't document MyClass then its functions would be seen as global.  Everything doesn't need a description so one-line "keyword: title" comments are fine if you just need to change the scope.

Documenting all your code elements is easy to remember, but if you're going from documenting a class to documenting globals you have to remember to manually set the scope back using a section comment:

// Class: MyClass
public class MyClass
   {
   // Function: MyMemberFunction
   public void MyMemberFunction ()
      { ... }
   }

// Section: Globals

// Function: MyGlobalFunction
public void MyGlobalFunction ()
   { ... }

Scopes do not nest, so any time you declare one you have to use the full namespace:

namespace MyCompany.MyProject
   {
   // Class: MyCompany.MyProject.MyClass
   public class MyClass
      {
      // Class: MyCompany.MyProject.MyClass.MyNestedClass
      public class MyNestedClass
         { ... }
      }
   }

If you were to follow MyNestedClass with more members of MyClass, you would need to declare that scope again with "Class: MyCompany.​MyProject.​MyClass".  It's recommended that you put nested classes at the end of their parents' declarations so you don't have to switch back and forth like this.  It will also make the generated documentation cleaner.

When your programming language has full support that means Natural Docs has a parser written specifically for it and can interpret its code.  Rather than following the rules above, everything uses the code's actual scope:

namespace MyCompany.MyProject
   {
   // Class: MyClass
   public class MyClass
      {
      // Function: MyFunction
      public void MyFunction ()
         { ... }
      }

   public class AnotherClass
      {
      // Function: AnotherFunction
      public void AnotherFunction ()
         { ... }
      }
   }

// Function: MyGlobalFunction
public void MyGlobalFunction ()
   { ... }

Everything is more tolerant.  You can use just "Class: MyClass" and Natural Docs will know the full name is MyCompany.​MyProject.​MyClass.  It will know AnotherFunction is part of MyCompany.​MyProject.​AnotherClass even though AnotherClass wasn't documented.  And it will know MyGlobalFunction is global even though there was no section comment.

The code's scope applies to standalone comments as well:

// About: License
// This code is licensed under the GPL.

public class MyClass
   {
   // About: Thread Safety
   // This class is not designed to be thread safe.
   }

Like functions appearing in the same places, these comments have scope.  License is global and Thread Safety is part of MyClass.  You would link to it from other classes with <MyClass.Thread Safety>.

Text files always use comment scope, even if you mainly use a language with full support.  So for example if you wanted to use the database keywords to document your schema, you would do something like this:

Database Table: MyTable

   Database Column: MyColumn

   Database Column: MyColumn2

The database table keyword starts a scope, so MyColumn and MyColumn2 will be seen as part of MyTable.  Documenting another table will change the scope, and you need to use a section comment to go back to global.

Enums are a special case.  They automatically behave like list comments so you can document their members in the same place.

/* Enum: CounterMode

   Normal - Causes the counter to increment normally.
   Odd    - Causes the counter to only increment in odd numbers.
   Even   - Causes the counter to only increment in even numbers.
*/
enum CounterMode { Normal, Odd, Even };

The comment above would allow you to not only link to CounterMode but also to CounterMode.Normal, CounterMode.Odd, and CounterMode.Even.

The exact scope of the values depends on the language.  For some they will be global (Even), while for others they will appear under the enum (CounterMode.Even or ClassName.​CounterMode.​Even).  Still for others they will appear on the same level as the enum (Even or ClassName.Even).  It should default to what's appropriate for your language.  If a language only has basic support this behavior is defined by the Enum Values setting in Languages.txt.