You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Follow-up to #234, item 4 ("Automatically update and add api documentation").
Deferred out of #234's scope by ADR-0021
(decision 4).
Problem
There is no generated API reference for the ~20 Informedica.*.Lib projects. The
XML documentation comments the F# coding standard requires
(.github/instructions/fsharp-coding.instructions.md) are written but never
rendered anywhere — the only navigable documentation is hand-written prose under docs/domain/ and docs/mdr/, which describes the domain model rather than the
public API surface.
Scope to decide
Tool: fsdocs (F#-native,
understands F# signatures and can also render the existing Scripts/*.fsx as
literate docs) vs docfx (broader .NET tooling, weaker F# rendering). fsdocs is
the obvious starting candidate for an all-F# solution.
Which projects: all 20+ libraries is a lot of surface area, much of it
internal. Starting with the libraries that have a genuinely public contract
(GenUNITS, GenSOLVER, GenCORE, GenFORM, GenORDER, GenPRES.Shared) may be more useful than everything at once.
Hosting: GitHub Pages from master vs published per release. None of this
infrastructure exists yet — there is no gh-pages branch and no Pages config.
Enforcement: whether missing/malformed XML docs should warn or fail the
build. Turning this on repo-wide would be noisy immediately; scoping it to
newly-touched files is the gentler option.
Prerequisite: GenerateDocumentationFile is not currently set in Directory.Build.props, so no XML doc files are emitted at all today. That has
to be turned on first (and will surface a wave of FS3390/missing-doc warnings).
MDR note
Generated API documentation is process/reference material, not clinical logic. It
does not replace anything in docs/mdr/ and should not be treated as a Design
History File input — the hand-written domain and design-history documents remain
authoritative.
Follow-up to #234, item 4 ("Automatically update and add api documentation").
Deferred out of #234's scope by
ADR-0021
(decision 4).
Problem
There is no generated API reference for the ~20
Informedica.*.Libprojects. TheXML documentation comments the F# coding standard requires
(
.github/instructions/fsharp-coding.instructions.md) are written but neverrendered anywhere — the only navigable documentation is hand-written prose under
docs/domain/anddocs/mdr/, which describes the domain model rather than thepublic API surface.
Scope to decide
understands F# signatures and can also render the existing
Scripts/*.fsxasliterate docs) vs docfx (broader .NET tooling, weaker F# rendering). fsdocs is
the obvious starting candidate for an all-F# solution.
internal. Starting with the libraries that have a genuinely public contract
(
GenUNITS,GenSOLVER,GenCORE,GenFORM,GenORDER,GenPRES.Shared) may be more useful than everything at once.mastervs published per release. None of thisinfrastructure exists yet — there is no
gh-pagesbranch and no Pages config.master, or only when a release lands (whichwould pair with Publish the Docker image automatically on release #459 and reuse
release.yml's "a release happened" signal).build. Turning this on repo-wide would be noisy immediately; scoping it to
newly-touched files is the gentler option.
GenerateDocumentationFileis not currently set inDirectory.Build.props, so no XML doc files are emitted at all today. That hasto be turned on first (and will surface a wave of FS3390/missing-doc warnings).
MDR note
Generated API documentation is process/reference material, not clinical logic. It
does not replace anything in
docs/mdr/and should not be treated as a DesignHistory File input — the hand-written domain and design-history documents remain
authoritative.