Re: Question about doc style

new topic     » goto parent     » topic index » view thread      » older message » newer message
irv said...

I notice that in many (most?) of the docs, an example is given like the following:

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

 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.

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?

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. 


new topic     » goto parent     » topic index » view thread      » older message » newer message


Quick Links

User menu

Not signed in.

Misc Menu