Fixes for Issue related to MATLAB/Octave documentation Issue #302

[deepanshu-zade]

What type of PR is this? (check all applicable)

• [ x ] Refactor
• Feature
• [ x ] Bug Fix
• Optimization
• Example
• [ x ] Documentation

Description

1. Added multi-line support for PURPOSE because it used to break the content and spill out into DESCRIPTION (See Issue Issue related to MATLAB/Octave documentation #302 )
2. Bug fix for optional parameters in DESCRIPTION, as they were shown out of order
3. Replaced SYNOPSIS with SYNTAX tag and lists the different ways that a function can be called (In case of function overloading mimics MATLAB documentation)

Related Issues & Documents

• [ x ] I have created an Issue that is paired with this PR
• Closes Issue related to MATLAB/Octave documentation #302

QA Instructions, Screenshots, Recordings

Check ReadTheDocs

Added/updated tests?

_We encourage you to test all code included with MOLE, including examples.

• [ x ] Yes
• No, and this is why: please replace this line with details on why tests
  have not been included
• I need help with writing tests

Read Contributing Guide and Code of Conduct

• [ x ] 📖 I have read the MOLE Contributing Guide: https://github.com/csrc-sdsu/mole/blob/main/CONTRIBUTING.md
• [ x ] 📖 I have read the MOLE Code of Conduct: https://github.com/csrc-sdsu/mole/blob/main/CODE_OF_CONDUCT.md

[optional] Are there any post deployment tasks we need to perform?

[optional] What gif best describes this PR or how it makes you feel?

[Tony-Drummond]

I have reviewed these changes with @deepanshu-zade. All the .m files are updated because Deepanshu implemented a script that standardized the header for all MATLAB/Octave scripts, and now using documentation the tags like; Purpose, Syntax, and Description.
We will wait for another reviewer before merging to the main branch.

[pritkc]

Thank you @deepanshu-zade for the the contribution.

---

• python3 -m py_compile doc/sphinx/source/_ext/matlab_doc_filter.py -- OK
• doc/sphinx HTML build completes; have some remaining Sphinx warnings look pre-existing and unrelated to this PR

---

adding a non-blocking follow up below, you can either append that here, or we can do merge them as a follow-up, whichever best works for you.

Among git-tracked src/matlab_octave/**/*.m, 13 files still have no PURPOSE tag (grid snippets under grids/{chevron,horseshoe,swan}/ and generateWeights.m). With the PR’s formatter, first_desc_line stays empty for those, so the rendered PURPOSE section is blank unless you add tags or restore a legacy fallback.
suggestions --
A) Restore legacy “first meaningful line” behaviour when there is no PURPOSE block so grid helpers and generateWeights.m still get a one-line PURPOSE in the HTML
OR
B) add minimal PURPOSE / DESCRIPTION / SYNTAX blocks to those 13 src files so they match the rest of the library.

---

Edge case — PURPOSE/SYNTAX regions are closed on any line that matches \b(DESCRIPTION|…)\b. A sentence that contains those words could, in theory, end a block early. Unlikely in current headers but worth knowing.

[pritkc]

Fallback option logic would like something similar to the below -

    if not first_desc_line.strip():
        for line in lines:
            s = line.strip()
            if not s:
                continue
            if re.search(
                r'[-]{10,}|SPDX-License-Identifier:|© \d{4}-\d{4}|See LICENSE file',
                s,
            ):
                continue
            body = re.sub(r"^\s*%\s?", "", s).strip()
            if re.match(
                r"^(PURPOSE|DESCRIPTION|SYNTAX|LICENSE)\s*:?\s*$",
                body,
                re.IGNORECASE,
            ):
                continue
            first_desc_line = s
            break