If you use nlapiGetField(fldnam) in a client script to return a nlobjField object, the object returned is read-only. [...] you cannot use nlobjField setter methods to set field properties. There is one exception, nlobjField.setDisplayType can be used to set the display type.” Further down the same page: “you cannot use setDisplayType to set the field’s display type. The nlobjField object returned from nlapiGetField(fldnam) is read-only”

I think there was some special mention as to where all you can use that. I think it works only in client script. That too for Suitelets (where you have UI form object) (Not sure though. But I have scripts running this API/method). Also a thing you might wanna consider while experimenting is - nlobjField.setDisabled(true); true for making it disabled or false otherwise.

i just cannot believe how much the documentation contradicts itself…

Yeah, the documentation is poor and confusing is what I have come to believe. Although the documentation is vast, but not that useful at times. https://suitecoder.appspot.com/static/api.html is where you can see it.

perfect, thanks @Nik bookmarks