All CLA requirements met.

The actual 'indentation' strategy is actually 'indentation & predefined markers'.
Instead of adding a new strategy, what about extending the 'indentation' strategy to 'indentation & predefined markers & user markers'.
IMO that would fit better with the current story (and would fix #36002).

@aeschli I agree, for #36002, the pull request need to be reworked.

But let's review the current folding strategies:

• auto -> (block | indentation) & predefined markers
• indentation -> indentation & predefined markers

If we add user markers, we get:

• auto -> (block | indentation) & predefined markers & user markers
• indentation -> indentation & predefined markers & user markers
  That's fine.

But, the explicit strategy is a predefined markers | user markers only strategy.
Why do I need that strategy?

It's about readability of code (even with correctly formatted and commented code).
When you open a file with more than 2000 lines, at first glance, it's difficult to know its structure, what's in it and what's going on.
So, you fold the code to see its structure.
But with auto and indentation strategies, the folding become tricky. For example, if you have a class in a namespace, the class disappears. You have to unfold the namespace, and then unfold the class to read its properties or methods.
With the explicit strategy, you can see immediately the structure of the code (if there are markers). You dan't have to unfold the if/for block in functions.

In vim, it's the marker method
In jEdit, it's the explicit mode

I hope I was good enough so you can see the advantage to add another strategy 😃

Just some food for thought (and clarification on what auto means):

Besides the indentation based folding strategy, we also have ranges coming from folding range providers. Folding range providers can be added by extensions through code. We have such providers for TypeScript, JSON, CSS...

'auto' means the best available strategy is chosen.
If a folding range provider is available, its ranges will be used.
If more than one folding provider is available, all ranges will be merged (best effort).

• auto -> (folding range provider results) or (indentation & predefined markers)
• indentation -> indentation & predefined markers

Note that folding range provider have full control of the ranges. Neither indention based ranges nor predefined markers are merged in. Instead, we expect the folding range provider to correctly add ranges for the predefined markers (he has a better understanding of the language and can better detect markers in comments or string literals.

You could implement your feature also as a folding range provider. But if another extension also provides folding provider for the language, both will be merged, resulting in the extra nesting that you described above.
The idea is to allow give a folding range provider a name which then could be referenced in the folding strategy.

I've tried with an extension (Zokugun Folding) which add user markers (in a quick&dirty way).

But with the auto strategy, the problems are:

• multiple markers (markers defined in the language and by the extension)
• folding ranges provided by the language (I only want markers)

I see three ways to resolve those:

• add the explicit strategy
• add a none strategy to bypass both auto and indentation. Then I rename my extension as Explicit Folding (with some fixes).
• add settings for the folding range provider:
  • to allow user markers
  • to disable folding ranges of statements, block, declarations, ...

The third option would be the best because like you said, the folding range provider has a better understanding of the language. But it would need to be modified to support those new settings.

So the second one can be good solution until all folding range providers support the new settings.

What do you think?

I see two ways:
a.

• new user setting for folding markers and new only-markers strategy
• indentation strategy uses: indentation & predefined markers & user markers
• only-markers strategy uses: predefined markers & user markers

b.

• allow folding range provider to have an id

interface FoldingRangeProvider {
     id?: string;
     providerFoldingRanges(...) ...
}

• allow the user to enter that id as a strategy

 "editor.foldingStrategy": "zukogun"

I would go with b. It's better than my none strategy.

But I have a question, should the auto strategy exclude FoldingRangeProviders which have an id?

I'd have auto merge all providers, like it is now. What do you think?

Yes, that's fine.

What is the next step?

If you have interest (and time) a PR would be great. Unfortunately, I don't know when I will have cycles to work on it.

The PR has been submitted and the updated extension is available at zokugun/vscode-explicit-folding.

closed in favor of #54200