Clearly mark functions that should not be used outside of their project

Problem/Motivation

Both core and contrib have code that is intended for internal use only, and should not be called from other contrib modules or custom code. This can be functions, interfaces, or certain methods.

On D7, this was indicated for functions by prefixing the function name with an underscore. That's great if you know what it means, but isn't at all clear if you don't know the convention.

We should have an indication in the docblocks for these functions or interfaces. Currently we have either:

• @internal
• Nothing (most functions)
• "(internal use only)" in the one line description (e.g. _theme)
• @deprecated (e.g. _drupal_add_js)

Of these three I think "(internal use only)" is the best because it's most visible, but it's still not totally clear what qualifies as internal and uses characters in the one-line description. @deprecated is just plain wrong - the functions can still be used, but only by internal code.

Benefits

If we adopted this change, the Drupal Project would benefit by ...

Three supporters required

1. Gogowitsch
2. joachim
3. {link to user}

Proposed changes

Provide all proposed changes to the Drupal Coding standards. Give a link to each section that will be changed, and show the current text and proposed text as in the following layout:

1. documentation on function declarations

Current text

function funstuff_system($field) {
  $system["description"] = t("This module inserts funny text into posts randomly.");
  return $system[$field];
}

Arguments with default values go at the end of the argument list. Always attempt to return a meaningful value from a function if one is appropriate.

Anonymous functions should have a space between "function" and its parameters, as in the following example:

array_map(function ($item) use ($id) {
  return $item[$id];
}, $items);

Proposed text

function funstuff_system($field) {
  $system["description"] = t("This module inserts funny text into posts randomly.");
  return $system[$field];
}

Arguments with default values go at the end of the argument list. Always attempt to return a meaningful value from a function if one is appropriate.

Anonymous functions should have a space between "function" and its parameters, as in the following example:

array_map(function ($item) use ($id) {
  return $item[$id];
}, $items);

A function outside of classes, interfaces and traits cannot be marked as private. Instead, you can mark functions that are not to be called from outside the project by starting their name with an underscore. In addition, use the @internal annotation.

/**
 * @internal
 */
function _private_funstuff_system($field) {
  $system["description"] = t("This module inserts funny text into posts randomly.");
  return $system[$field];
}

2. Repeat the above for each page or sub-page that needs to be changed.

Remaining tasks

1. Create this issue in the Coding Standards queue, using the defined template
2. List three supporters
3. Create a Change Record
4. Review by the Coding Standards Committee
5. Coding Standards Committee takes action as required
6. Tagged with 'Needs documentation edits' if Core is not affected
7. Discussed by the Core Committer Committee, if it impacts Drupal Core
8. Documentation updates
   1. Edit all pages
   2. Publish change record
   3. Remove 'Needs documentation edits' tag
9. If applicable, create follow-up issues for PHPCS rules/sniffs changes

For a fuller explanation of these steps see the Coding Standards project page