1. Question about doc style
- Posted by irv Sep 06, 2019
- 883 views
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.
2. Re: Question about doc style
- Posted by _tom (admin) Sep 06, 2019
- 883 views
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
3. Re: Question about doc style
- Posted by ghaberek (admin) Sep 06, 2019
- 846 views
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
4. Re: Question about doc style
- Posted by _tom (admin) Sep 06, 2019
- 878 views
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
5. Re: Question about doc style
- Posted by irv Sep 06, 2019
- 850 views
Yes, this makes things much clearer!
6. Re: Question about doc style
- Posted by ghaberek (admin) Sep 06, 2019
- 868 views
I kind of prefer the readability of having a routine's declaration right in the docs.
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 =
7. Re: Question about doc style
- Posted by irv Sep 06, 2019
- 857 views
I kind of prefer the readability of having a routine's declaration right in the docs.
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
8. Re: Question about doc style
- Posted by euphoric (admin) Sep 06, 2019
- 843 views
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.)
9. Re: Question about doc style
- Posted by euphoric (admin) Sep 06, 2019
- 860 views
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.
10. Re: Question about doc style
- Posted by petelomax Sep 07, 2019
- 855 views
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.
11. Re: Question about doc style
- Posted by irv Sep 07, 2019
- 853 views
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.