Euphoria
Ticket #498:
eudoc should list namespace xyz as it would any other constant
-
Reported by
ne1uno
Dec 05, 2010
pages created for a library module should have
=== namespace xyz if a namespace is used.
Details
1. Comment by jeremy
Dec 05, 2010
See what you think of what I just did. I'm afraid if it's output at the top of the page and one jumps right to a method, say man:std_cmdline#cmd_parse from search, then they will have no idea what namespace it resides in. I added the namespace output in the item signature just like the include is.
What do you think? Oh.. check in the current online docs, right on the above link (or any place in the API section).
2. Comment by jeremy
Dec 05, 2010
Another option I just thought of could be:
include std/cmdline.e -- default namespace 'cmdline'
public function cmd_parse(sequence opts, object parse_options = {}, sequence cmds = command_line())
3. Comment by DerekParnell
Dec 05, 2010
The usage in the online manual is fine by me ...
include std/cmdline.e
namespace cmdline
public function cmd_parse(sequence opts, object parse_options = {},
sequence cmds = command_line())
4. Comment by jeremy
Dec 05, 2010
I like it as well.
ne1uno, if you have any complaints and suggestions about it, please put it back to new, but I am going to mark it fixed, please confirm.
5. Comment by jimcbrown
Dec 05, 2010
Jeremy's fix is fine with me. Not that I read the manual or anything......
6. Comment by ne1uno
Dec 05, 2010
jim is write only?
I think having namespace in every item is a little too busy. euphoria programmers, the intended audience, will be able to figure out the namespace belongs to the whole module if it is just listed once. you shouldn't have to open the include file to find out what it is though.
given the choice
include std/cmdline.e -- namespace 'cmdline'
reads a little better, note: default makes no sense. not sure if only the first or last namespace is valid or if it's an error to have more than one.
if there is no namespace, one shouldn't be included even though eudoc will assign a default.
7. Comment by jeremy
Dec 06, 2010
Its no more noisy or out of place than the include. I kind of like it being there for the reason of pointing people to places in the docs. Not everything in common knowledge, for example hash.e is namespace stdhash and sequence.e is stdseq, because of built in methods by those names.
Linking to man:std_sequence#mapping will give the person everything they need to know to use the method. That's what I like. No browsing around for different details.
8. Comment by mattlewis
Dec 06, 2010
I like the combination of "include...namespace...signature." Very succinct, and puts the information right where it will be useful.
9. Comment by ne1uno
Dec 06, 2010
how about
--namespace xyz
include specialxyz.e
public routine fun()
that way on a copy and paste, we are less likely to see conflicting namespace statements in user code.
10. Comment by jeremy
Dec 06, 2010
I don't think many people will be copying the item signature and pasting into code?
11. Comment by jeremy
Dec 07, 2010
Marking as fixed, no further comments it seems.
GitHub