Docs

Writing Matft documentation

Matft's documentation has two layers.

Both are built by .github/workflows/docs.yml and published to GitHub Pages (https://jjjkkkjjj.github.io/Matft/, API at /Matft/api/documentation/matft). CI treats DocC warnings as errors and broken site links as errors, so pass the same checks locally before opening a PR.

The README is only an entry point (overview, examples, installation, links). Do not add details to the README; write them on the site and link to them.

1. Decide what to update

Where each kind of change needs to be reflected. The NumPy mapping tables and the Topics in Matft.md are the ones most often missed.

2. Doc comments (API reference)

Read the implementation before writing

Comments describe how the implementation actually behaves. Guessing from the signature or old comments publishes a false spec on DocC. In particular, check these in the implementation:

• Supported types, and the mftype of the result (e.g. integer input becomes Float)
• Whether complex is supported: if it calls unsupport_complex(...), it is not → write it in - Precondition:
• The meaning of defaults such as axis / keepDims, and the behavior when axis is omitted
• Whether the return value is a view (shares memory with the original) or a copy
• If it throws, which MfError cases it throws (only cases actually thrown)
• Differences from Numpy (scipy / cv2 / PIL / librosa)

When the implementation and the comment disagree and you cannot tell which is intended (i.e. a suspected bug), do not fix the code: make the comment match the actual behavior and report the suspicion to the user. The fix goes in a separate PR following the TDD rule in CLAUDE.md. Fixing code on the side during documentation work sneaks in untested behavior changes.

Format

Match the existing format of each file (/** ... */ or ///). Do not mix them.

/**
   Return the indices of the elements that are non-zero.

   Equivalent to `numpy.nonzero`. NaN counts as non-zero. The indices are listed in row-major order.

   - Parameters:
        - mfarray: The input array.
   - Returns: One 1-d `.Int` array per dimension of `mfarray`, holding the indices of the non-zero elements along that dimension.
   - Precondition: Complex arrays are not supported.
*/
public static func nonzero(_ mfarray: MfArray) -> [MfArray]{

• First line: a one-sentence summary (shown in DocC listings). Details after a blank line.
• If there is a counterpart, write Equivalent to \numpy.xxx`.` (likewise for cv2 / PIL / transformers / librosa / scipy).
• List every argument under - Parameters: (capital P). Names must match the internal names in the signature (a mismatch causes a DocC warning → CI failure). Do not write meaningless descriptions like mfarray: mfarray.
• - Returns: / - Throws: / - Precondition: / - Note: (differences from Numpy and caveats).
• For method versions, write Method version of \Matft.transpose(_:axes:)`.` and repeat only the key points.
• For operators, write the Numpy counterpart (*& is @, === is element-wise ==, == is numpy.array_equal).
• For internal helpers that happen to be public, write - Note: This is an implementation detail of Matft and may change. Do not change the access level.
• Document protocol requirements on the requirement. No need to document each conforming implementation for Int / Float etc. (DocC inherits the requirement's description).
• Use ``Symbol`` double-backquote links only when you are sure they resolve. Unresolved links become warnings, so normally write code.
• Write in English.

Code examples

Add short ```swift examples only to major entry points (creation functions, commonly used operations, image/audio preprocessing, etc.). If you include output, copy values straight from a test or use only results actually run as in 4. Never guess output.