OpenEuphoria

Re: Question about doc style

• Posted by _tom (admin) Sep 06, 2019
• 898 views

include console.e  
namespace console  
public procedure display(object data_in, object args = 1,... 

_tom 
 
 the eudoc program grabs these details from the source-code,  
creole shoves them into the documentation 
 
**namespace console** is not really //assigning// a namespace,  
just showing you what //was// assigned 
 
my version of eudoc also creates: include std/console.e 
 

What I notice is that we are assigning a namespace to console (yes, that previous line needs to be fixed to be std/console.e)

But std/console.e already has a namespace: console.

so this is a redundant assignment "for documentation purposes" 
 

And nowhere in the demo program is display() used with a namespace, i.e. console:display().

I have thought of writing console:display() in the examples, but this is messy. 
 
Sadly, the namespace feature has resulted in some  duplication of identifiers. It would 
have been more elegant if, at least for common names, there would be no dupes. 
 

So, there seems little point in complicating things by assigning a namespace that duplicates the namespace it already owns. Especially if we never use it!

We should leave that line out, and only re-assign and/or use a namespace when it helps to clarify the demo or differentiate calls which use the same keyword.

_tom 
 
docs should point out that this is the default namespace 
 
again, included to "remind" reader what the default is 
 

Or am I missing something obvious that I have never run into before?

_tom 
 
I have experimented with putting things into a table,  
or/and reverting back to the original RDS style (much like Phix uses) 
 
ultimately (when my parsing skills get better) I figure the way to do things is  
to chop up up all details, then put them into a database, then format them to taste. 
 
Creole has been traditionally used to format to the exact "look" that ends up 
in the documentation. This is inflexible and sometimes messy. 
 

_tom