Discussion: Documenting CLI Flags – Same Page vs Separate Pages in DocC

Related Projects ArgumentParser
, ,
1

Hello everyone,

I was looking at ways to make CLI documentation better with Swift DocC. I found something that made me think. I want to hear what you think about it before I do anything else.

Now commands usually show all flags on the same page. One thing we could do is let each flag have its page with a link that always works. This would make it easy to go to a specific flag and add more documentation for each flag.

This might not be all good. If a lot of flags only have information, having separate pages could mean we end up with a lot of pages that are mostly empty. The command page would still need to list all the flags so people can find them.

So it seems like we have an option:

  1. Only document flags on the command page.
  2. Make pages for flags with links that always work.
  3. Let developers choose how they want to do it.

Before we decide on anything, I want to ask you:

  • Do you think each flag should have its own page?
  • Should they just be on the command page?
  • If both ways are good, would it be helpful to be able to choose which way we want to do it?
  • I would like to hear how you like to look at CLI documentation. If having separate pages for flags would be helpful in real life.

I would like you all to answer based on your experiences. I will definitely add in my proposal that while implementing a better solution, I am leaning more towards not making lots of empty files.
So, if you can also suggest any other better structure that you would like to see, that would be awesome.

Thanks!

2

I think both options should be available. As a concrete example, the git-log man page has this entry:

--follow

Continue listing the history of a file beyond renames (works only for a single file).

That’s all that really needs to be said for that option, and it feels like having a whole documentation page for it would not add a lot of value. But it also has this entry:

--pretty[=<format>], --format=<format>

Pretty-print the contents of the commit logs in a given format, where <format> can be one of oneline, short, medium, full, fuller, reference, email, raw, format:<string> and tformat:<string>. When <format> is none of the above, and has %placeholder in it, it acts as if --pretty=tformat:<format> were given.

See the "PRETTY FORMATS" section for some additional details for each format. When =<format> part is omitted, it defaults to medium.

Note: you can specify the default pretty format in the repository configuration (see git-config(1)).

That is way too much information to put at the top level, and the “PRETTY FORMATS” section at the bottom has a large amount of content that should really be moved to at least one separate page but is still closely tied to this specific option. I think if this were to be a DocC page I would just want to see:

--pretty[=<format>], --format=<format>

Pretty-print the contents of the commit logs in a given format.

And then have that link to a page with the full details, examples, and nested page(s)s for the custom format reference. Is there maybe a way to have entries in the topic lists that aren’t actually separate pages? You would be able to tell them apart by color (and underlining?) and then options could naturally be expanded to their own page if the amount of content expands past a sentence.

2 Likes
3

Yes, exactly, you have given a great example of what the problem really is that I am facing. I am gonna look into how to categorize which description is too long, and which description is straightforward (one liner).

I have to see how the link of the pages might work.

Are we talking about new commands that are key-based (shift + somekey)? or adding new flags for full description purposes.

I believe you are talking about underlines used something like

--follow
Continue listing the history of a file beyond renames.

--pretty[=]
Pretty-print commit logs.
→ (link to detailed page)

I will look for the answer to whether we can have entries in the topic lists that aren’t actually lists.

4

Oh sorry I had a typo there. I meant “have entries in the topics list that aren’t actually separate pages”

5

I’ve been thinking more about the “same page vs separate pages” question for documenting CLI flags in DocC, and it feels like the right direction is a hybrid model rather than choosing one strictly.

- The command page should remain the primary entry point and list all flags with concise, one-line descriptions.

- Only flags that actually need more explanation would get expanded into detailed views, while simple flags stay inline.

- This keeps the overview intact without losing depth where it matters.

- One idea I wanted to explore further: instead of spreading detailed descriptions across many small files, could we keep all extended flag documentation in a single source (or a small structured set) and fetch from it when needed?

- Each flag would always have a short summary on the command page, but if it has richer content, that detail could live centrally and be pulled into a separate page or section when accessed.

- Would something like this fit within DocC’s current model, or would it require a preprocessing step before generating the documentation?

- This could help avoid creating lots of low-value or nearly empty pages while keeping authoring simple (one place for detailed content).

- It still allows multi-page or expandable documentation where appropriate.

- Could this integrate cleanly with symbol graphs or documentation extensions, or would it be better handled entirely during generation?

- For deciding when a flag should get that detailed treatment, we could keep it predictable:

  • description exceeds ~1–2 lines

  • includes examples

  • introduces formats or multiple modes

  • needs explanation beyond a straightforward definition

  • Otherwise, it stays inline.

I am curious if this direction aligns with how others are thinking about scaling CLI documentation in DocC, and whether the “central source + selective expansion” model sounds feasible within the current tooling.

I would appreciate any help since application period for GSoC has started, for that I am ready to add some time to concrete the implementation by creating prototypes, and engage in threads.