[DISC][C++] Conventions for Mentioning Classes and Methods in Documentation

[Kae Suarez <ka...@gmail.com>]

Hello,

I am currently creating some new documentation here:
https://github.com/apache/arrow/pull/13859, and would like to enhance other
documentation over time, so I would like to figure out best practices.
However, some areas lack standardization in the documentation.

In particular, classes are referred to in multiple ways. This is making it
difficult to make new documentation in a semi-standardized manner, and I
would like to see about standardizing this.

In https://arrow.apache.org/docs/cpp/compute.html, a namespace is used in
Sphinx to be able to use class directives (which create links to relevant
locations in API documentation) in short form. Most functions are referred
to using orange text, and classes are referred to in orange text after
their introduction (a style similar to wikis, in which something has a
hyperlink the first time, then is plaintext afterwards.)

In https://arrow.apache.org/docs/cpp/arrays.html, there is a mix, where
terms such as "Arrow array" are used alongside class directives that use
the full namespace qualifiers.

In https://arrow.apache.org/docs/cpp/dataset.html, when a class is
mentioned directly, it has its full namespace included in a class directive
each time.

I personally like the idea of using namespace directives in Sphinx to keep
things less cluttered and easier to write, then using the class directive
each time so links are always available. As for functions, I'd like to keep
them in "orange text," unless they are unconnected to a class in use in the
article -- if they are, I would like to use directives there, as well. What
would all of you prefer as a standard? I would want to use the determined
direction in the documentation I am creating, and would want to propagate
it through existing articles over time.

Kae Suarez

Re: [DISC][C++] Conventions for Mentioning Classes and Methods in Documentation

[Antoine Pitrou <an...@python.org>]

Le 30/08/2022 à 21:08, Kae Suarez a écrit :
> I do not know about the namespace issue in the API reference, but when
> focusing on the User's Guide and Getting Started sections, we can announce
> at the top of the page what namespace is relevant. I personally recommend
> using only the arrow namespace for ease in documentation and being more
> manual with the ones after that (e.g., using compute::CallFunction()
> instead of CallFunction() or arrow::compute::CallFunction()). This way,
> users will know that we're generally using Arrow's namespace, and any
> namespace is contained therein and important to keep an eye on.

Yes, that sounds like a good idea.

Thanks for doing this!

Best regards

Antoine.

Re: [DISC][C++] Conventions for Mentioning Classes and Methods in Documentation

[Kae Suarez <ka...@gmail.com>]

I do not know about the namespace issue in the API reference, but when
focusing on the User's Guide and Getting Started sections, we can announce
at the top of the page what namespace is relevant. I personally recommend
using only the arrow namespace for ease in documentation and being more
manual with the ones after that (e.g., using compute::CallFunction()
instead of CallFunction() or arrow::compute::CallFunction()). This way,
users will know that we're generally using Arrow's namespace, and any
namespace is contained therein and important to keep an eye on.

As for "always linking," sure! I can do that, and we can see how it looks
in the PR I'm working on. Thanks for the feedback, I'll be back in a while
with some real-world results.

Kae Suarez

On Tue, Aug 30, 2022 at 1:57 PM David Li <li...@apache.org> wrote:

> "Always linking" sounds reasonable to me. It also makes the decision
> easier, for both author and reviewer.
>
> I feel like there must be some way to configure Breathe or Sphinx to show
> the namespace in Antoine's example, but I don't see it…
>
> On Tue, Aug 30, 2022, at 08:52, Antoine Pitrou wrote:
> > Hello Kae,
> >
> > Le 29/08/2022 à 19:28, Kae Suarez a écrit :
> >>
> >> I personally like the idea of using namespace directives in Sphinx to
> keep
> >> things less cluttered and easier to write, then using the class
> directive
> >> each time so links are always available.
> >
> > I would agree with this. As for the namespace, though, one question is
> > how the user might derive in which namespace a class lives?
> >
> > For example,
> >
> https://arrow.apache.org/docs/cpp/api/dataset.html#_CPPv4N5arrow7dataset7DatasetE
> > doesn't mention that the class lives in the arrow::dataset namespace.
> >
> >  >
> >   As for functions, I'd like to keep
> >> them in "orange text," unless they are unconnected to a class in use in
> the
> >> article -- if they are, I would like to use directives there, as well.
> >
> > I would rather see functions/methods hyperlinked as well, as much as
> > possible.
> >
> > Regards
> >
> > Antoine.
>

Re: [DISC][C++] Conventions for Mentioning Classes and Methods in Documentation

[David Li <li...@apache.org>]

"Always linking" sounds reasonable to me. It also makes the decision easier, for both author and reviewer. 

I feel like there must be some way to configure Breathe or Sphinx to show the namespace in Antoine's example, but I don't see it…

On Tue, Aug 30, 2022, at 08:52, Antoine Pitrou wrote:
> Hello Kae,
>
> Le 29/08/2022 à 19:28, Kae Suarez a écrit :
>> 
>> I personally like the idea of using namespace directives in Sphinx to keep
>> things less cluttered and easier to write, then using the class directive
>> each time so links are always available.
>
> I would agree with this. As for the namespace, though, one question is 
> how the user might derive in which namespace a class lives?
>
> For example, 
> https://arrow.apache.org/docs/cpp/api/dataset.html#_CPPv4N5arrow7dataset7DatasetE 
> doesn't mention that the class lives in the arrow::dataset namespace.
>
>  >
>   As for functions, I'd like to keep
>> them in "orange text," unless they are unconnected to a class in use in the
>> article -- if they are, I would like to use directives there, as well.
>
> I would rather see functions/methods hyperlinked as well, as much as 
> possible.
>
> Regards
>
> Antoine.

Re: [DISC][C++] Conventions for Mentioning Classes and Methods in Documentation

[Antoine Pitrou <an...@python.org>]

Hello Kae,

Le 29/08/2022 à 19:28, Kae Suarez a écrit :
> 
> I personally like the idea of using namespace directives in Sphinx to keep
> things less cluttered and easier to write, then using the class directive
> each time so links are always available.

I would agree with this. As for the namespace, though, one question is 
how the user might derive in which namespace a class lives?

For example, 
https://arrow.apache.org/docs/cpp/api/dataset.html#_CPPv4N5arrow7dataset7DatasetE 
doesn't mention that the class lives in the arrow::dataset namespace.

 >
  As for functions, I'd like to keep
> them in "orange text," unless they are unconnected to a class in use in the
> article -- if they are, I would like to use directives there, as well.

I would rather see functions/methods hyperlinked as well, as much as 
possible.

Regards

Antoine.