Contradictory documentation in EEPROM library

[rustycoat]

The EEPROM library examples and primary header is poorly documented and gives the wrong impression that 8k of simulated EEPROM is avialable through the library:

"There is no EEPROM built into the Apollo3 Cortex-M4F but we have 1M of flash
so we carve out the last 8k of flash for EEPROM space."

I purchased my Artemis boards based on this specific, but after encountering unexplained freezes after writing to locations after 1023, I have scoured the header file to see that outside of the primary comments at the top, there is a comment that the EEPROM size is actually limited to 1024 (unless you want to run with your own forked variant of the Arduino core and modify AP3_FLASH_EEPROM_SIZE).

Although since this is an open source project I could modify the header if needed, that would separate me from future bugfixes and feature additions.

Although I could submit a pull request on a re-phrase of the documentation, I don't feel this is appropriate for an end-user: SparkFun is a company, selling a product. It is their responsibility to chose how they wish to document these things in a more responsible manner (and ideally, SparkFun should provide real documentation, not comments at the top of each header file, or worse, scattered throughout the source).

[oclyke]

@rustycoat thank you for opening this issue. Documentation is admittedly a challenging aspect of many open-source projects. We are hoping to improve our process in that regard in the near future. In the meantime I wanted to address your desire to use more than 1024 bytes of Flash memory for EEPROM emulation. In the above pull request (#127) we added the ability to configure up to 8192 bytes of usable EEPROM. Here's example usage:

EEPROM.setLength(2048);

or

EEPROM.setLength(AP3_EEPROM_MAX_LENGTH); // defined maximum length

You can also see this in action in the updated Example2_AllFunctions.ino test sketch.

Note: larger EEPROM sizes will increase RAM usage and execution time

(This changes will be available to all users in the next release, until then you can clone this repo and check out the corresponding branch - or the master branch once it has been merged)

[rustycoat]

Thank you, having that configurable via a programmatic interface completely and permanently solves the issue, functionality wise. The comments in the example file are clear (but I do think the header still has a conflicting statement, which I indicated with a comment). Also I noted a potential bug (and a fix) if setLength is given an out of range value. I am new to github PRs and such, so I didn't know how to contribute other than the comments.

Thanks for the speed and serious response.