1. Question about doc style

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,... 

First of all, include console.e won't work in a program. It needs to be std/console.e. So a new programmer could be confused.

Secondly, "we" know that the second line is just reminding us that a namespace has already been assigned to std/console.e (don't we?). It isn't required to be there unless there's a specific reason: reasignment. So a new programmer could be confused, or just doing extra typing for nothing.

Thirdly, in the demo following, nowhere is console:display() called. Just display(). Further confusion, I think.

Perhaps there's a better, less confusing way to do this.

new topic     » topic index » view message » categorize

2. Re: Question about doc style

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,... 

_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

new topic     » goto parent     » topic index » view message » categorize

3. Re: Question about doc style

I think users need a way to know the default namespace for a library, and I believe that it should be present somewhere in the docs, but it doesn't have to be listed everywhere.

Maybe the top of the doc page for each library could summarize this information?

-Greg

new topic     » goto parent     » topic index » view message » categorize

4. Re: Question about doc style

The "signature" could be re-designed to be more explicit.

signature display(object data_in, object args = 1,...
type procedure
located in file std/console.e
default namespace console
scope public

for functions the table is extended...

function returns return values...

This is doable without re-typing the docs. Parsing the output from eudoc lets me do this. Then, the results are fed into creole as before.

_tom

new topic     » goto parent     » topic index » view message » categorize

5. Re: Question about doc style

Yes, this makes things much clearer!

new topic     » goto parent     » topic index » view message » categorize

6. Re: Question about doc style

I kind of prefer the readability of having a routine's declaration right in the docs.

public procedure display(object data_in, object args = 1, integer finalnl = - 918_273_645)


I think it's a lot easier to grok since that's how I'll be writing it. I know it's scope, routine type, and required/optional parameters all in one line.

-Greg

P.S. apparently if you need to include an equal symbol = in a heading, you need to use the escape sequence =

new topic     » goto parent     » topic index » view message » categorize

7. Re: Question about doc style

ghaberek said...

I kind of prefer the readability of having a routine's declaration right in the docs.

public procedure display(object data_in, object args = 1, integer finalnl = - 918_273_645)


I think it's a lot easier to grok since that's how I'll be writing it. I know it's scope, routine type, and required/optional parameters all in one line.

-Greg

P.S. apparently if you need to include an equal symbol = in a heading, you need to use the escape sequence =

Nothing wrong with this either - but it reminds me of something that we might be smart to take into account: if the html docs are designed with this in mind, it would be possible to create a help() function for WEE, the Bear, and possibly some 3rd party editors without a lot of trouble.

A help() function that would keep up when changes and additions were made, via a simple rescan. Saving someone a ton of work. See, for example, the bear_help_index.e in demos/bear. It was (mostly) automatically generated, but still humanly fixable smile

new topic     » goto parent     » topic index » view message » categorize

8. Re: Question about doc style

ghaberek said...

I think users need a way to know the default namespace for a library, and I believe that it should be present somewhere in the docs, but it doesn't have to be listed everywhere.

Maybe the top of the doc page for each library could summarize this information?

It's fine the way it is. I use the docs all the time, and I was never confused that that was syntax. It's showing the function details... name, namespace, parameters.

If you're going to change it, it better be for the better. (I like Tom's idea of it being a table, so long as the proc/func signature is maintained and obvious.)

new topic     » goto parent     » topic index » view message » categorize

9. Re: Question about doc style

_tom said...

The "signature" could be re-designed to be more explicit.

signature display(object data_in, object args = 1,...
type procedure
located in file std/console.e
default namespace console
scope public

for functions the table is extended...

function returns return values...

This is doable without re-typing the docs. Parsing the output from eudoc lets me do this. Then, the results are fed into creole as before.

_tom

I like this idea, because finding the parameters and output of the function would be much easier/quicker with visual distinctiveness.

new topic     » goto parent     » topic index » view message » categorize

10. Re: Question about doc style

irv said...

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

include std/console.e  
namespace console  

Secondly, "we" know that the second line is just reminding us that a namespace has already been assigned to std/console.e (don't we?).

As I understand it, the second line is a brand new namespace applying to this file, whereas

include std/console.e as console 

would be the one that (needlessly) replicates the existing namespace already defined within std/console.e.

new topic     » goto parent     » topic index » view message » categorize

11. Re: Question about doc style

petelomax said...
irv said...

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

include std/console.e  
namespace console  

Secondly, "we" know that the second line is just reminding us that a namespace has already been assigned to std/console.e (don't we?).

As I understand it, the second line is a brand new namespace applying to this file, whereas

include std/console.e as console 

would be the one that (needlessly) replicates the existing namespace already defined within std/console.e.

That is correct, except that a file's namespace has to be declared before any other line of code in that file, (except comments, I think) so putting it after the include std/console.e line is just going to result in a "Unknown namespace used" error.

We can't cause trouble by doing that, because Eu catches the error. But if it is invalid, then the docs shouldn't show it as if it was. A slight change so that it's clearer, such as:

include std/console.e 
-- all console.e functions have the default namespace "console:" 

That would avoid implying that you should ever add a namespace x line after an include.

new topic     » goto parent     » topic index » view message » categorize

Search



Quick Links

User menu

Not signed in.

Misc Menu