DOC: pandas.DataFrame.to_hdf missing data

[hunterhogan]

Pandas version checks

• I have checked that the issue still exists on the latest versions of the docs on main here

Location of the documentation

https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.to_hdf.html

Documentation problem

1. Section "Returns" is missing.
2. Section "Raises" is missing.

Said differently, in the HTML source, "Parameters" is a defined term, but "Returns" and "Raises" are not in the HTML source.

  <dl class="py method">
    <dt class="sig sig-object py" id="pandas.DataFrame.to_hdf">
    ...
    <dd>
    ... 
      <dt class="field-odd">Parameters
...

Suggested fix for documentation

The data for those sections probably exists, but it isn't being published by the automated process. I tried to figure out where the rst file lives, but I gave up after half an hour.

[jbrockmendel]

Did a human write this issue?

[Alvaro-Kothe]

The data for those sections probably exists

It doesn't exist, you can click [source] in the function documentation page and it redirects you to the function source code. The function documentation presented in the docs is the function docstring

Section "Returns" is missing.

Dataframe.to_hdf doesn't return anything, for me its optional that it includes a Returns section.

Section "Raises" is missing.

This is a valid point, and it's important to document possible errors. In order to keep track of this, it's important to look at the call stack and confirm the errors that could happen and the circumstances under which they could happen.

[hunterhogan]

Did a human write this issue?

srsly? When I write an issue or pull request, I feel like I am playing Russian roulette. Maybe people appreciate my effort; maybe people will be neutral; or maybe people will be aggressive.

"You wrote too much."

"You didn't give us enough information."

But now I need to write in such a way that some programmer, oh, excuse me, software "engineer", won't dismiss my attempt to contribute because of their assessment of my writing: you know, because comp sci programs have rigorous writing training, and half of the writers in Hollywood are burnt-out developers.

Just add another check box or field to your Issue forms: "Did a human write this issue?" The forms already have 26 required fields, so why not add another?

[source]

I kept clicking on "Show Source," which doesn't have much information. I don't know why I didn't click on [source]. Thank you for pointing that out.

doesn't return anything, for me its optional

Documentation has been a serious problem in IT since forever. I'm very happy things have improved dramatically since I quit IT in 2005, but there are still systemic issues. For example: if a function does not have a return, should the docstring have a Returns section? Yes or no, not "Eh, maybe." I've been reading a lot of the pandas docs and I had already seen functions that said Returns None, so that set my expectations. Therefore, when I couldn't find the section in the documentation, my prior experience suggested to me that it was an error.

This issue

I don't care if y'all add the sections or not. I mistakenly thought the information was not being displayed due to an error. So I opened an issue because I mistakenly thought I was being helpful.

[Alvaro-Kothe]

Sorry for the AI usage accusation, but I understand @jbrockmendel. Pandas has a large influx of AI-generated issues and PRs (e.g., #62168, #62272, #62183, #62184), which, more often than not, end up being a complete waste of time. And several pandas core members have to go through them. So I ask for your empathy in this regard.

I don't know why I didn't click on [source]. Thank you for pointing that out.

Glad to help, this is a sphinx feature, and it's used by several other major projects like PyTorch, Jax, Scikit-learn, and NLTK.

should the docstring have a Returns section?

As long as it adds context. For me, just saying that it returns None is useless because you can get this information from LSPs. Anyway, documentation contributions are always welcome!

[jbrockmendel]

But now I need to write in such a way that some programmer, oh, excuse me, software "engineer", won't dismiss my attempt to contribute because of their assessment of my writing

Yes. Snark aside, yes. It's a bummer but a fact of life. Luckily, "getting indignant about it" is an effective strategy, at least until the bots start emulating it.