Replacing a file should change the name.

It's been some time this problem has been reported.
Just want to add this comment to put some focus on it again.

I'm torn about this. Changing the filename will render all existing public links broken so I'm not sure it's a good idea if you are actually replacing a file to keep the same file id but give it a different filename. Calling replace on the filemanager api means we want a new file to replace the existing file inside the site not add / delete. Changing the filename creates a situation where private and public file access reacts differently to the same function. Since private links use the file id and not the filename their links would still work.

We basically have three options that don't generate the different behaviors:
1) Leave as is where file id to filename mapping is set in stone once a file is added to the repository.
2) Remove updating from the API and make it a add new / delete operation.
3) Switch private urls to reference filename and change the filename on update.

I really don't like option 3 as it creates a confusing situation for module developers whose intention was to replace a file in context. Meaning the want to the file to show up where the old file did. Changing the file name and or file id creates a situation where the module author may have to search and replace URLs which can be problematic. In addition it would create interesting problems for site maintainers during upgrade to search and replace all existing links that use file id.

Option 2 removes some functionality but is a very clear and straight forward API. It will be readily obvious to a new module developer that they are destroying an old file id and creating a new one. I really don't want to remove the capability to remove items in place with out updating external links... as a matter of fact the attachment module relys on this functionality.

I'm inclined to leave the API as is but add more comments to the function header. Please let me know what you think.