NaturalDocs::SymbolTable::IndexElement

This is a little tricky, so make sure you understand this.  Indexes are sorted by symbol, then packages, then file.  If there is only one package for a symbol, or one file definition for a package/symbol, they are added inline to the entry.  However, if there are multiple packages or files, the function for it returns an arrayref of IndexElements instead.  Which members are defined and undefined should follow common sense.  For example, if a symbol is defined in multiple packages, the symbol’s IndexElement will not define File(), Type(), or Prototype(); those will be defined in child elements.  Similarly, the child elements will not define Symbol() since it’s redundant.

Diagrams may be clearer.  If a member isn’t listed for an element, it isn’t defined.

A symbol that only has one package and file

[Element]
- Symbol
- Package
- File
- Type
- Prototype
- Summary

A symbol that is defined by multiple packages, each with only one file

[Element]
- Symbol
- Package
    [Element]
    - Package
    - File
    - Type
    - Prototype
    - Summary
    [Element]
    - ...

A symbol that is defined by one package, but has multiple files

[Element]
- Symbol
- Package
- File
   [Element]
   - File
   - Type
   - Protype
   - Summary
   [Element]
   - ...

A symbol that is defined by multiple packages which have multiple files

[Element]
- Symbol
- Package
   [Element]
   - Package
   - File
     [Element]
     - File
     - Type
     - Prototype
     - Summary
     [Element]
     - ...
   [Element]
   - ...

Why is it done this way?

Because it makes it easier to generate nice indexes since all the splitting and combining is done for you.  If a symbol has only one package, you just want to link to it, you don’t want to break out a subindex for just one package.  However, if it has multiple package, you do want the subindex and to link to each one individually.  Use HasMultiplePackages() and HasMultipleFiles() to determine whether you need to add a subindex for it.

Combining Properties

All IndexElements also have combining properties set.

So if an IndexElement only has one definition, CombinedType() is the same as the TopicType and PackageSeparator() is that of the definition’s language.  If other definitions are added and they have the same properties, the combined properties will remain the same.  However, if they’re different, they switch values as noted above.

Sortable Symbol

SortableSymbol() is a pseudo-combining property.  There were a few options for dealing with multiple languages defining the same symbol but stripping different prefixes off it, but ultimately I decided to go with whatever the language does that has the most definitions.  There’s not likely to be many conflicts here in the real world; probably the only thing would be defining it in a text file and forgetting to specify the prefixes to strip there too.  So this works.

Ties are broken pretty much randomly, except that text files always lose if its one of the options.

It’s a pseudo-combining property because it’s done after the IndexElements are all filled in and only stored in the top-level ones.