Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[DOC] Change to handling of aliases #7340

Merged
merged 1 commit into from Feb 19, 2023
Merged

[DOC] Change to handling of aliases #7340

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
11 changes: 1 addition & 10 deletions doc/contributing/documentation_guide.md
View file
Open in desktop
Expand Up @@ -241,7 +241,6 @@ The general structure of the method documentation should be:
- Details and examples.
- Argument description (if necessary).
- Corner cases and exceptions.
- Aliases.
- Related methods (optional).

### Calling Sequence (for methods written in C)
Expand Down Expand Up @@ -328,7 +327,7 @@ Return types:

Aliases:

- Omit aliases from the `call-seq`, but mention them near the end (see below).
- Omit aliases from the `call-seq`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would clarify that in rare circumstances aliases can be listed in the call-seq. @zverok provided an example for String#-@ and String#dedup. In this case (operator and normal method are aliases), it probably makes sense to list both. In this case, the operator and method can both be listed.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure how to characterize the exceptional cases. Would you please add something to the doc?


### Synopsis

Expand Down Expand Up @@ -398,14 +397,6 @@ you do not need to document that a `TypeError` is raised if a non-integer
is passed. Do not provide examples of exceptions being raised unless
that is a common case, such as `Hash#fetch` raising a `KeyError`.

### Aliases

Mention aliases in the form

```
// Array#find_index is an alias for Array#index.
```

### Related Methods (optional)

In some cases, it is useful to document which methods are related to
Expand Down