<commit_before># Configuration

The following table shows which tags can appear in which contexts.
The first four can appear in any of the rest so are not listed in the content column explicitly.

| Configuration | Content | Meaning |
| ------------- | ------- | ------- |
| `<trusts>` | Name of the class or package or `*` for all. | Who can access the containing API element. |
| `<distrusts>` | Ditto | Like `<trusts>` but revokes access. |
| `<name>` | A dotted Java identifier | Specifies a Java package, class, or class member. |
| `<rationale>` | Human readable text | An error message shown when a sibling `<distrusts>` triggers. |
| <hr /> | <hr /> | <hr /> |
| `<api>` | Many `<package>`, `<class>` | A group of sensitive API elements. |
| `<package>` | 1 `<name>`, many `<package>`, `<class>` | A java package. |
| `<class>` | 1 `<name>`, many `<class>`, `<method>`, `<field>`, `<constructor>` | A Java class. |
| `<method>` | 1 `<name>` | Specifies a method in the enclosing `<class>` |
| `<field>` | 1 `<name>` | Specifies a field in the enclosing `<class>` |
| `<constructor>`| | Specifies a constructor in the enclosing `<class>` |

For example,

```XML
<api>
  <package>
    <name>com</name>
    <package>
      <name>example</name>
      <class>
        <name>NameOfClass</name>
        <trusts>org.trustworthy.Accessor</trusts>
        <distrusts>*</distrusts>
        <rationale>
          NameOfClass exposes authority that must be used in
          accordance with strict guidelines (see ...).

          Try to use com.example.SimplerSaferAlternative instead.

          If that doesn't suffice, email <EMAIL> and
          they will work with you to find a way to use the simpler
          APIs or approve your uses.
        </rationale>
      </class>
    </package>
  </package>
</api>
```

specifies that `org.trustworthy.Accessor` can use
`com.example.NameOfClass` but not other classes.

Names can be dotted, so the configuration above can be simplified to

```XML
<class>
  <name>com.example.NameOfClass</name>
  <trusts>org.trustworthy.Accessor</trusts>
  <distrusts>*</distrusts>
  <rationale>...</rationale>
</class>
```

## Writing good `<rationale>`s.

The `<rationale>...</rationale>` element may appear in any API element.
When a user builds code that violates the policy, the rationale is shown.

It should

1. Explain or give short link to documents explaining how to work within
   the policy.<commit_msg>Added anchor to "Writing good rationales" section<commit_after># Configuration

The following table shows which tags can appear in which contexts.
The first four can appear in any of the rest so are not listed in the content column explicitly.

| Configuration | Content | Meaning |
| ------------- | ------- | ------- |
| `<trusts>` | Name of the class or package or `*` for all. | Who can access the containing API element. |
| `<distrusts>` | Ditto | Like `<trusts>` but revokes access. |
| `<name>` | A dotted Java identifier | Specifies a Java package, class, or class member. |
| `<rationale>` | Human readable text | An error message shown when a sibling `<distrusts>` triggers. |
| <hr /> | <hr /> | <hr /> |
| `<api>` | Many `<package>`, `<class>` | A group of sensitive API elements. |
| `<package>` | 1 `<name>`, many `<package>`, `<class>` | A java package. |
| `<class>` | 1 `<name>`, many `<class>`, `<method>`, `<field>`, `<constructor>` | A Java class. |
| `<method>` | 1 `<name>` | Specifies a method in the enclosing `<class>` |
| `<field>` | 1 `<name>` | Specifies a field in the enclosing `<class>` |
| `<constructor>`| | Specifies a constructor in the enclosing `<class>` |

For example,

```XML
<api>
  <package>
    <name>com</name>
    <package>
      <name>example</name>
      <class>
        <name>NameOfClass</name>
        <trusts>org.trustworthy.Accessor</trusts>
        <distrusts>*</distrusts>
        <rationale>
          NameOfClass exposes authority that must be used in
          accordance with strict guidelines (see ...).

          Try to use com.example.SimplerSaferAlternative instead.

          If that doesn't suffice, email <EMAIL> and
          they will work with you to find a way to use the simpler
          APIs or approve your uses.
        </rationale>
      </class>
    </package>
  </package>
</api>
```

specifies that `org.trustworthy.Accessor` can use
`com.example.NameOfClass` but not other classes.

Names can be dotted, so the configuration above can be simplified to

```XML
<class>
  <name>com.example.NameOfClass</name>
  <trusts>org.trustworthy.Accessor</trusts>
  <distrusts>*</distrusts>
  <rationale>...</rationale>
</class>
```

## Writing good `<rationale>`s. <a name="writing_good_rationales"></a>

The `<rationale>...</rationale>` element may appear in any API element.
When a user builds code that violates the policy, the rationale is shown.

It should

1. Explain or give short link to documents explaining how to work within
   the policy.
{'fraction_non_alphanumeric': 0.14990932903485796, 'fraction_numerical': 0.0020149103364900263, 'mean_word_length': 3.2210884353741496, 'pattern_counts': {'":': 0, '<': 133, '<?xml version=': 0, '>': 133, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '910410', 'n_tokens_mistral': 1626, 'n_tokens_neox': 1495, 'n_words': 563}