Consider different docs for different TFMs

[dsyme]

From @TheAngryByrd in #1055

At some point, we'll have to fix how we do API generation. A single project can return multiple results (for instance, you get a different result per TFM). Which could change the API documentation. We'll either have to have a TFM chooser like MSDN does or some other way to denote some APIs are only available per TFM.

[github-actions]

🤖 This is an automated response from Repo Assist.

Great observation from @TheAngryByrd! This is a significant architectural consideration. Here's a brief analysis:

Current Situation

fsdocs currently runs project cracking once and generates a single set of API docs. When a project targets multiple TFMs (e.g., net6.0;net8.0), Ionide.ProjInfo returns separate ProjectOptions per TFM — but only one set of symbol data ends up in the docs.

Implementation Options

Option A: TFM selector UI (like MSDN / .NET API Browser)

• Generate API docs for each TFM separately, then merge into a single HTML page with a dropdown to toggle between views
• Complex to implement; requires significant changes to the HTML template and CSS
• Most user-friendly for consumers of the docs

Option B: Lowest-common-denominator

• Only document APIs that exist in all targeted TFMs (intersection)
• Much simpler; avoids a UI change
• Loses visibility of TFM-conditional APIs (e.g., APIs guarded by #if NET8_0_OR_GREATER)

Option C: Per-TFM output directories

• Generate a separate docs subfolder per TFM, let users navigate between them
• Avoids merging logic; easy to implement
• Less seamless UX than a selector

Option D: Single "richest" TFM

• Pick the TFM with the most APIs (typically the latest) and document that
• Simple, but hides APIs only available on older TFMs

Suggested Approach

Option A is the gold standard, but Options B or D could be a pragmatic interim approach with a clear migration path toward A later. The key challenge in any option is the ProjectCracker phase — it needs to surface multi-TFM awareness so GenerateModel can decide how to aggregate.

This is a moderately large feature. A good first step would be to add structured tracking of which TFM each CrackedProject was built for, so the information is available when generating models.

Generated by Repo Assist

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/repo-assist.md@da02dddebe71d9a937665abdcd1f5214dab852a7