Euphoria
Ticket #654:
Documentation includes internal standard library routines as if they should be called by users of the standard library
-
Reported by
SDPringle
Apr 16, 2011
Symbols we want exported within the standard library but not outside of the library1 are in the documentation and it is something I never meant for people to call directly. Things like dep_works have an export qualifier because they need to be visible in std/machine.e. If left in the documentation, it should go into some library internals section.
I am putting this under Documentation because that is the end result. The root of the matter is in eudoc, ofcourse. However, filing this under 'Feature Request' with 'Bundled Utility' would obscure the required result.
I want to express a result in the ticket type and category rather than the method. One could always edit euphoria.txt before running creole. In fact, I could add that to the installer creation procedure or use some kind of filtering script and that would satisfy this result.
1. Consider this example:
std/memory.e
export function dep_works()
...
end function
std/safe.e
export function dep_works()
...
end function
std/machine.e
if dep_works()
...
I want to discourage code in the following block
foo.ex
-- dep_works() is only accessable here if you include std/safe.e or std/memory.e
-- It is in the documentation so the user might do just that.
-- We never meant the user to do this:
include std/safe.e
-- nor this:
if dep_works() then
...
Details
1. Comment by ne1uno
Apr 16, 2011
there is an example in include/std/utils.e
@nodoc@
that is not quite right though, really needs to be
@devdoc@
that can be optionally collected into a supplement developer section. anyone using eudoc/creole in their own projects will have the same problem leaking too many implementation details into the user docs.
2. Comment by SDPringle
May 21, 2011
I noticed that in eumem.e everything is exported. I suppose this is intentional and prefered over public. graphicst.e has export variables that are for internal use.
Sockets contain two constants with an 'export' access but it isn't used anywhere in the library. Why not just leave them local?
3. Comment by SDPringle
May 25, 2011
I have noticed that you have to be careful with whitespace with eucode. Being used to C and EUPHORIA I wasn't careful about this and found things...
wouldn't work with:
-- **
-- @nodoc@
It must have the same whitespace like the following:
--**
-- @nodoc@
4. Comment by SDPringle
May 25, 2011
I would like it to appear that all of the routines for low level access and safe low level access are in std/machine.e.
5. Comment by SDPringle
Jun 15, 2011
This is fixed in the 4.0 branch in 95c9d5ce38d5 and in the 4.1 trunk in 8a24b171ad8e
6. Comment by SDPringle
Jun 15, 2011
See: hg:euphoria/rev/7ce68e714662
changeset: 4963:7ce68e714662 branch: 4.0 user: Shawn Pringle <shawn.pringle@gmail.com> date: Wed Jun 15 18:08:36 2011 -0300 files: docs/release/4.0.3.txt description:
- records the fix of ticket 654 in release notes
GitHub