issue-35: Write responses with files onto disk incrementally

[wiitt]

Solves #35
In this PR, I tried not to ruin the logic of throwing (logging) errors and kept it as it used to be.
However, I think that it might be better to modify a bit the way how we do it. I would probably replace this endCode stuff in a writing function (it was save_as_file, now it's response_to_file) with throwing errors in when an unexpected exception occurs and "skip" messages when a file is skipped. It was the other way around before (raising errors for unpermitted overwriting files and logging messages for errors), and now I moved overwriting errors to a different level, but still not sure that it belongs there. I'd better have "skip" messages on the level of file consumer (the deepest possible level) and raising errors in response_to_file.

[KristenMeyerONC]

Can you add Matlab version requirements to the documentation (perhaps also the readme of the repo as well)

[wiitt]

Weirdly enough, confluence says that I cannot even see the documentation page in wiki. Like I don't have permission when I'm logged in.

[KristenMeyerONC]

You can make a systems ticket and request permission to edit the page you need to in the wiki or I can do it for you

[KristenMeyerONC]

Can you also add a version note to the GettingStarted documentation: https://github.com/OceanNetworksCanada/api-matlab-client/blob/main/doc/GettingStarted.html#L6

The comment in the HTML file implies that the file was auto-generated but I'm not familiar with how that was actually done... I personally would just edit the HTML

Also, have we confirmed that this works on R2018a? I'm seeing 2022b in https://github.com/OceanNetworksCanada/api-matlab-client/blob/main/info.xml#L9 (maybe that should be updated to R2022b? Might be why the file exchange has different version requirements.). You can probably test R2018a editing https://github.com/OceanNetworksCanada/api-matlab-client/blob/main/.github/workflows/matlab.yml and rerunning checks

[wiitt]

Now I see what you meant about the auto-generated documentation. Yes, I wasn't right that there are no docs. Idk, I think I even saw it at some point, but, when I wanted to get back to it, I chose the only "wrong" file (xml) in the docs folder. So, I decided that I the documentation, I saw before, was for Python.

Do you think we need "source code" sections in the docs? Wouldn't it be sufficient to replace them with links to files on github?

No, I didn't confirm the work on R2018a. I solely relied on wiki documentation and checked MATLAB versions which all newly used classes/functions were added at. I agree that it would be better to actually test the client on R2018a, especially if this haven't been previously done yet.

P.S. I'll create a ticket for getting permission to edit the wiki, thanks.

[spencerwplovie]

No, I didn't confirm the work on R2018a. I solely relied on wiki documentation and checked MATLAB versions which all newly used classes/functions were added at. I agree that it would be better to actually test the client on R2018a, especially if this haven't been previously done yet.

Based on https://jira.oceannetworks.ca/browse/DMAS-82515, it looks like the DAQ team has gotten the client library to work on a few Matlab versions - based on the comments, as old as R2019a and as recent as R2024a. But this is for varying CL versions; v2.1.1 and v2.2.0. Still worth testing to make sure, just an FYI.

[KristenMeyerONC]

Do you think we need "source code" sections in the docs? Wouldn't it be sufficient to replace them with links to files on github?

Oh I see. It looks like the doc HTML files are generated from the actual .m source code. I think Matlab is auto adding the "source code" sections.

Eg: https://github.com/OceanNetworksCanada/api-matlab-client/blob/main/doc/Onc.html
https://github.com/OceanNetworksCanada/api-matlab-client/blob/main/onc/Onc.m

However, GettingStarted does not have a corresponding .m file so maybe just edit the HTML to add the version info for that one?

[wiitt]

Dropped one commit from this PR and created #37 to address version compatibility issues in a separate PR.