"hidden" public package functions

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

"hidden" public package functions

Olaf Till-2
Hi,

currently the developers page at the OF website says:

  If the package contains functions which for some reason should not
  be advertised, they can be listed under the category ‘Internal’ in
  the INDEX file. In the future, this category will be handled
  specially in generating the online documentation.

I'm not sure anymore about the last sentence. Arguments (Julien) for
such non-private but not advertised functions were:

- experimental functions,

- helper functions which may also be directly used, but normally are
  not.

But treating a category 'Internal' in a special way would mean some
complications to the code of generate_html and of the website. And the
only thing we could achieve by this would be not exposing the helptext
of such functions (the function name must still be listed to enable
checking for defined symbols).

Is this really worth the effort? Would it not be equivalent, or even
better, to expose the help text, but to state the special status of
the function in it -- i.e. 'This function should be considered
experimental ... (help text follows)' or 'undocumented internal
function' (with help only as a comment in the source)?

Olaf

--
public key id EAFE0591, e.g. on x-hkp://pool.sks-keyservers.net

signature.asc (836 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: "hidden" public package functions

jbect
Le 18/06/2017 à 18:43, Olaf Till a écrit :

> currently the developers page at the OF website says:
>
>    If the package contains functions which for some reason should not
>    be advertised, they can be listed under the category ‘Internal’ in
>    the INDEX file. In the future, this category will be handled
>    specially in generating the online documentation.
>
> I'm not sure anymore about the last sentence. Arguments (Julien) for
> such non-private but not advertised functions were:
>
> - experimental functions,
>
> - helper functions which may also be directly used, but normally are
>    not.
>
> But treating a category 'Internal' in a special way would mean some
> complications to the code of generate_html and of the website. And the
> only thing we could achieve by this would be not exposing the helptext
> of such functions (the function name must still be listed to enable
> checking for defined symbols).
>
> Is this really worth the effort? Would it not be equivalent, or even
> better, to expose the help text, but to state the special status of
> the function in it -- i.e. 'This function should be considered
> experimental ... (help text follows)' or 'undocumented internal
> function' (with help only as a comment in the source)?

Isn't it ok if the package manager simply omits these functions from the
INDEX ?

(In the stk package I put them in comments.)

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: "hidden" public package functions

Olaf Till-2
On Sun, Jun 18, 2017 at 10:36:16PM +0200, Julien Bect wrote:

> Le 18/06/2017 à 18:43, Olaf Till a écrit :
> >currently the developers page at the OF website says:
> >
> >   If the package contains functions which for some reason should not
> >   be advertised, they can be listed under the category ‘Internal’ in
> >   the INDEX file. In the future, this category will be handled
> >   specially in generating the online documentation.
> >
> >I'm not sure anymore about the last sentence. Arguments (Julien) for
> >such non-private but not advertised functions were:
> >
> >- experimental functions,
> >
> >- helper functions which may also be directly used, but normally are
> >   not.
> >
> >But treating a category 'Internal' in a special way would mean some
> >complications to the code of generate_html and of the website. And the
> >only thing we could achieve by this would be not exposing the helptext
> >of such functions (the function name must still be listed to enable
> >checking for defined symbols).
> >
> >Is this really worth the effort? Would it not be equivalent, or even
> >better, to expose the help text, but to state the special status of
> >the function in it -- i.e. 'This function should be considered
> >experimental ... (help text follows)' or 'undocumented internal
> >function' (with help only as a comment in the source)?
>
> Isn't it ok if the package manager simply omits these functions from the
> INDEX ?
>
> (In the stk package I put them in comments.)
I know. But they should be known to the website, to enable duplicate
checking. And if they are listed at the pages relevant for duplicate
checking, there should, IMO, also exist a page with the function help
text, for consistency. I wouldn't have thought that exposing an
appropriate function help text should be problematic.

That's my suggestion. If you leave them out of INDEX, or comment them,
there'll be no duplicate checking for them. Well, that wouldn't be
fatal in this case, probably. But it's not ideal.

Anyway, I think I'll remove the statement 'this category (Internal)
will be handled specially...' from the developers page.

Olaf

--
public key id EAFE0591, e.g. on x-hkp://pool.sks-keyservers.net

signature.asc (836 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: "hidden" public package functions

jbect
Le 19/06/2017 à 16:45, Olaf Till a écrit :
>> Isn't it ok if the package manager simply omits these functions from the
>> INDEX ?
>>
>> (In the stk package I put them in comments.)
> I know. But they should be known to the website, to enable duplicate
> checking. And if they are listed at the pages relevant for duplicate
> checking, there should, IMO, also exist a page with the function help
> text, for consistency.I wouldn't have thought that exposing an
> appropriate function help text should be problematic.

It is not *very* problematic.  I just prefer to avoid exposing the name
(not only the help text) of these functions.


> That's my suggestion. If you leave them out of INDEX, or comment them,
> there'll be no duplicate checking for them. Well, that wouldn't be
> fatal in this case, probably. But it's not ideal.

Certainly not fatal, since all functions in the stk package start with
the stk_ prefix.

So, as long as having *all* public functions and classes listed in the
INDEX is not mandatory for OF release, I prefer to leave things as they are.

Not ideal, I agree.  What would be ideal would be to have namespaces in
Octave ;-)


> Anyway, I think I'll remove the statement 'this category (Internal)
> will be handled specially...' from the developers page.

That's perfectly fine with me.

@++



Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: "hidden" public package functions

jbect
Le 19/06/2017 à 17:18, Julien Bect a écrit :

>> That's my suggestion. If you leave them out of INDEX, or comment them,
>> there'll be no duplicate checking for them. Well, that wouldn't be
>> fatal in this case, probably. But it's not ideal.
>
> Certainly not fatal, since all functions in the stk package start with
> the stk_ prefix.
>
> So, as long as having *all* public functions and classes listed in the
> INDEX is not mandatory for OF release, I prefer to leave things as
> they are.
>
> Not ideal, I agree.  What would be ideal would be to have namespaces
> in Octave ;-)

Oooops, I just found that we *do* have namespaces in Octave 4.2.1 at
least...

Loading...