Status "hidden"?

[adam_cameron]

Continuing the discussion from Classification of "features we don't think are a good way of coding anymore":

@micstriit

the status to “hidden”

What are the ramifications of some language element that has a status of “hidden”?

–
Adam

[dom_watson]

That it doesn’t appear in the documentation and that use of it is unsupported. Defo the first of those points, I’m presuming the latter. Its definitely an odd one.

[adam_cameron]

@dom_watson

That it doesn’t appear in the documentation and that use of it is unsupported. Defo the first of those points, I’m presuming the latter. Its definitely an odd one.

That’s a really dangerous combination.

So someone’s used a “hidden” bit of functionality and I inherit the codebase from them. I go to look in the docs and… nothing.

Is this a very good idea?

–
Adam

[Leftbower]

Languages/software contain “undocumented” features all the time. You use those undocumented features at your own risk. BUT if the suggestion is to change something from documented to undocumented, then - yeah - dangerous indeed.

[seancorfield]

@adam_cameron

So someone’s used a “hidden” bit of functionality and I inherit the codebase from them. I go to look in the docs and… nothing.

Is this a very good idea?

To me, that doesn’t seem any different to them using, for example, undocumented methods on the underlying Java objects that implement various data types. They shouldn’t have done it – and now you pay the cost of them using undocumented features.

[adam_cameron]

@seancorfield

To me, that doesn’t seem any different to them using, for example, undocumented methods on the underlying Java objects that implement various data types. They shouldn’t have done it – and now you pay the cost of them using undocumented features.

Very true. I was thinking - perhaps - of “hiding” something that was previously not hidden:

“nowServer” was a function mainly used by Railo in the admin and I think was never well adapted in the community[…] we should consider to set the status to “hidden” for this function for Lucee 5.

So not quite the situation you were speaking of Sean. But, yeah, we all seem to survive using the odd “undocumented” functions, and we don’t explode as a result. Probably not cool for the language vendor to do this though. They should just deprecate it [ducks for cover]

–
Adam

[apenhorwood]

I find it interesting we are discussing a status of “Hidden” when in the other thread I am still trying to get a list of what the status are.

[seancorfield]

Here’s my 2c:

For the CFML dialect:

• If Adobe says a CFML feature is “deprecated”, Lucee should say it is “deprecated” in the CFML dialect
• If Adobe says a CFML feature is “supported” (i.e., not “deprecated”), Lucee should also say it is “supported” in the CFML dialect

For the Lucee Language:

• Regardless of Adobe’s position on a CFML feature, Lucee could:
  • Continue to support it (as a documented feature)
  • Mark it “deprecated” if they think they might remove it in the future
  • Mark it “avoid” / “superseded” if they don’t like it but don’t yet plan to remove it
  • Mark it “hidden” (and please at least log to the console every time it is used)

For “hidden”, maybe a setting to throw an exception on use would help folks weed it out of their code.

Personally, I think “hidden” is a bit silly – either support it, deprecate it, or remove it. Similarly, I think that “avoid” / “superseded” are a bit silly too — again, either support it, deprecate it, or remove it.

For the CFML dialect, compatibility means there’s less wiggle room. For the Lucee Language, there’s no code out there yet so just have some conviction about the features!

[dom_watson]

@adam_cameron

Very true. I was thinking - perhaps - of “hiding” something that was previously not hidden:

This has been around for a pretty long time I believe. These are statuses for the internals of Lucee. There’s no suggestion that existing functionality will ever become hidden.

I think its pretty safe to ignore (have a hunt through the FLD/TLD files for the functions/tags with hidden statuses, it may make a little more sense - though I agree its a bit odd).

https://github.com/lucee/Lucee/blob/master/lucee-java/lucee-core/src/resource/fld/web-cfmfunctionlibrary_1_0
https://github.com/lucee/Lucee/blob/master/lucee-java/lucee-core/src/resource/tld/web-cfmtaglibrary_1_0

[apenhorwood]

OK, There are these status currently in the code:

deprecated
hidden
implemeted
unimplemeted

And these 4 status mean what at this point?

[dom_watson]

deprecated - Lucee dev’s advise using other methods
hidden - not official Lucee functionality and not to appear in documentation
implemented - Implemented
unimplemented - Not implemented

These files are for the internals of Lucee and also aid with the documentation (they formed the basis of Mark Drew’s railodocs + luceedocs).

[andrew]

Again, as per my comment on the other thread, it is documented here:

https://bitbucket.org/lucee/lucee/wiki/Statuses%20of%20functionality

[adam_cameron]

@andrew

Again, as per my comment on the other thread, it is documented here:

lucee / Lucee / wiki / Statuses of functionality — Bitbucket

Cheers Andrew. I have to admit I didn’t think to look anywhere other than docs.lucee.org for documentation. I forgot you had the Wiki as well.

To clarify further… is the wiki just a legacy thing, and eventually everything will be moved to the docs site, or is there a distinction between what docs are homed where or…?

–
Adam

[dom_watson]

@adam_cameron

To clarify further… is the wiki just a legacy thing, and eventually everything will be moved to the docs site, or is there a distinction between what docs are homed where or…?

Yes, plans are afoot to move into the docs site. [LD-45] - Lucee