DOC: Fixes after #17482
State: closed

- [X] tests added / passed
- [X] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`

Some doc fixes related to #17482:
- `func:` -> `:func:` 
    - See: https://github.com/pandas-dev/pandas/pull/17482#discussion_r139148962
- Added `cdate_range` to the public api so that it works in the docs
   - Ask for it to be added to docs:  https://github.com/pandas-dev/pandas/pull/17482#discussion_r138609092 
    - Public api issue pointed out: https://github.com/pandas-dev/pandas/pull/17482#discussion_r139148705
- Added `cdate_range` to `tests\api\test_api.py` to ensure that adding it to the top-level api is tested
- Removed the "experimental" from `cdate_range` docstring
    - See: https://github.com/pandas-dev/pandas/pull/17482#discussion_r138504193
- Fixed an error in the docstring for `interval_range` (strings aren't supported).

Labels:
name: Docs

Comments:
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/17554?src=pr&el=h1) Report
> Merging [#17554](https://codecov.io/gh/pandas-dev/pandas/pull/17554?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/328c7e179b72e257e27adf92a06718fd5a40473f?src=pr&el=desc) will **decrease** coverage by `0.01%`.
> The diff coverage is `100%`.

[![Impacted file tree graph](https://codecov.io/gh/pandas-dev/pandas/pull/17554/graphs/tree.svg?width=650&height=150&token=eZ4WkYLtcO&src=pr)](https://codecov.io/gh/pandas-dev/pandas/pull/17554?src=pr&el=tree)

```diff
@@            Coverage Diff             @@
##           master   #17554      +/-   ##
==========================================
- Coverage   91.25%   91.23%   -0.02%     
==========================================
  Files         163      163              
  Lines       49606    49606              
==========================================
- Hits        45266    45257       -9     
- Misses       4340     4349       +9
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `89.01% <100%> (ø)` | :arrow_up: |
| #single | `40.19% <100%> (-0.07%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/17554?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/indexes/datetimes.py](https://codecov.io/gh/pandas-dev/pandas/pull/17554?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9kYXRldGltZXMucHk=) | `95.53% <ø> (ø)` | :arrow_up: |
| [pandas/core/indexes/interval.py](https://codecov.io/gh/pandas-dev/pandas/pull/17554?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9pbnRlcnZhbC5weQ==) | `93.57% <ø> (ø)` | :arrow_up: |
| [pandas/core/api.py](https://codecov.io/gh/pandas-dev/pandas/pull/17554?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvYXBpLnB5) | `100% <100%> (ø)` | :arrow_up: |
| [pandas/io/gbq.py](https://codecov.io/gh/pandas-dev/pandas/pull/17554?src=pr&el=tree#diff-cGFuZGFzL2lvL2dicS5weQ==) | `25% <0%> (-58.34%)` | :arrow_down: |
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/pull/17554?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `97.77% <0%> (-0.1%)` | :arrow_down: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/17554?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/17554?src=pr&el=footer). Last update [328c7e1...72bccc6](https://codecov.io/gh/pandas-dev/pandas/pull/17554?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

One question for `cdate_range` is whether we actually want to add this to the top-level API. 
Can't you just specify a custom frequency with `date_range` ?
@jorisvandenbossche 

Yes, `cdate_range` can be replicated by specifying a custom frequency with `date_range`; this is essentially what `cdate_range` does under the hood.  The advantage to using `cdate_range` is purely convenience:  the user does not need create a custom frequency, and can instead just use parameters of `cdate_range` (which aren't valid parameters for `date_range`).

Really, there's even less of a case for `bdate_range`; the only difference between `bdate_range` and `date_range` is the default value of `freq`.  Seems like both `bdate_range` and `cdate_range` could be deprecated fairly easily, if we want to go that route.

thanks @jschendel you are very responsive! keep em' coming!
@jreback we were still discussing this. I am -1 (at this point) on adding this to the API.
@jschendel Ah, I didn't notice that `cdate_range` has those extra keywords (I thought it was just the different default frequency, like `bdate_range`). 
You are correct that `bdate_range` even gives less 'added' value (only the default freq), but I was wondering: can't we just merge the two functions? (I mean adding the functionality of the keywords to `bdate_range`) As it are both 'business-day'-related functions? Then we don't need to have both in the top-level namespace.

@jorisvandenbossche 

> I was wondering: can't we just merge the two functions?

From a technical standpoint this would be straightforward, and I'd be happy to submit a PR to do so, if that's what's ultimately decided.

Really, both `bdate_range` and `cdate_range` could be merged into `date_range` without a lot of effort. 
 Doesn't look like `bdate_range`/ `cdate_range` are used within the codebase other than tests, and a brief mention in the docs.  Aside from that, just a matter of adding the extra keywords to `date_range`, and directing users to change `cdate_range(...)` -> `date_range(..., freq='C')`, and `bdate_range(...)` -> `date_range(..., freq='B')`.  The same holds for just merging `cdate_range` into `bdate_range`, if that would be preferable.
I never use business frequency related functionality, so difficult to assess. 

I would suggest cdate_range -> bdate_range merge, as this is the easiest (cdate_range was not yet top-level, so we can easily remove it again). Merging both cdate_range/bdate_range in date_range is a bit more 'invasive' as this needs deprecating of  `bdate_range` (+ `bdate_range` is actually used in the docs, while `cdate_range` is not), so not sure that is worth.
@jorisvandenbossche : Okay, I'll open up an issue related to merging `cdate_range` -> `bdate_range` within the next day to give this more visibility, and to let others provide their input. I also never use business frequency related functionality, so difficult for me to assess too.