[Feature Request]: Add several flags to increase the verbosity of chpldoc

[Iainmon]

Summary of Feature

Adding certain flags to chpldoc that I think would really be useful to people.

This first flag is the most significant one of the bunch. It is a --ignore-nodoc, which would do the obvious: any method with the @chpldoc.nodoc attribute would just be ignored. This would be helpful for users like myself that are trying to use Chapel at its leading edge state or just understand what functions are immediately available. Many operations that I have needed are available, but I couldn't find without having to dig through the source code.

The next flag is has a similar motivation, but I suspect will be used less often. Sometimes, when trying to understand a certain Chapel internal module, I want to know all of the methods that are present, without being in the source file, or I want to have the source file open, and use the HTML docs as a high level outline. In these cases, I want some sort of --include-internal-fns that would prevent chpldoc from ignoring functions prefixed by chpl__*.

Along with the above, it would be great if there was a --include-internal-modules or something like it.

Next, there seemed to be some checking in chpldoc.cpp about whether or not to display a formal's intent. I think there should be an option such as --verbose-formals or something so that the formal's tag is explicitly added. When modifying my local chpldoc, I added deflt to be inserted for default intents, which made it much easier.

My intent 🤭 here is to discuss this collection of proposed chpldoc arguments for local doc generation that I think would make it easier for people trying to get started with Chapel. Thinking about last year, it would have been a lot easier getting started with Chapel if I had these available to me. Also, I have implemented these changes for myself, but I was reluctant to open several PRs and create tests, as that would take up much of my remaining two days.

I am excited to hear what you think!

[Iainmon]

chpldoc.cpp.txt
Here is the source file. I am just including it to show where I have added the effects the flags have on the generation. This file has some embarrassing tweaks and I hope that no one thinks I program like this :).

[lydia-duncan]

Many operations that I have needed are available, but I couldn't find without having to dig through the source code.

Iain, I think what you're asking for here is to know about implementation details in the standard and internal modules. Is that correct?

[lydia-duncan]

If so, I think there's a couple of tactics that could be taken:

• Things that you felt were useful but weren't visible to the user could have a feature request opened for making them more visible instead of having them nodoc'd
• Things that should be treated as implementation details (things we don't think should be exposed, chpl_ functions, internal module details, more explicit argument intent information, etc.) feels more appropriate for handling via a new flag called --devel as requested by Restore chpldoc --devel functionality? #6028. I would expect --devel to be automatically on when compiling with CHPL_DEVELOPER, similar to how it is handled in chpl compilation.
  • If we want more fine-grained control, it'd make sense for the additional flags to be only documented as developer flags, too

I suspect between the two of those tactics, we'll find that the things you're looking for would be handled. But it's totally reasonable to disagree, we'll just want to talk about it more :)