feature request: non-api doc marker

[lmiq]

The idea is to have a macro, let us say, INTERNAL, such that a message warning the user that the function is internal is shown instead of the actual help entry, and the help entry gets hidden inside an "Extended help" section.

That is, that some like this:

INTERNAL"""

f(x) 

This function always returns 1

# Example

example of use of f(x)

"""
f(x) = 1

gets parsed as:

"""

f(x)

**Internal function or structure - interface may change.**

# Extended help

This function always returns 1

# Example

example of use f(x)
"""

Such that when the user types ? f, he/she will get:

help?> f
search: f fd for fma fld fld1 fill fdio frexp foldr foldl flush floor float first fill! fetch fldmod filter falses

  f(x)

  Internal function or structure - interface may change.

  ────────────────────────────────────────────────

Extended help is available with `??`

Ps: I tried to implement this myself, but without a proper interaction with Documenter it does not really help much, and maybe others have the right expertise to do that (if they find the idea interesting, anyway). I have been using this pattern, by hand, in some packages, and it solves the problem of documenting inner functions without introducing possible confusions for the users.

[mortenpi]

If we decide on some API for this, then we can also get it into Documenter. There has been some discussion about something like this: JuliaDocs/Documenter.jl#1507 and JuliaDocs/Documenter.jl#1506

Marking docstrings private, rather than making them public, might be a nice way to go about this though. Do you have a proof-of-concept implementation with string interpolation?

[lmiq]

Not really, because it seems that string is not recognized as a doc entry if the tripled-quoted string is interpolated into a macro. But I'm pretty much ignorant about how these macros work, so I may be just missing a very basic thing here.

julia> macro INTERNAL_str(string)
           return(string)
       end
@INTERNAL_str (macro with 1 method)

julia> INTERNAL"""
           f(x)
       """
       f(x) = 1
f (generic function with 1 method)

help?> f
search: f fd for fma fld fld1 fill fdio frexp foldr foldl flush floor float first fill! fetch fldmod filter falses finally foreach

  No documentation found.

  f is a Function.

  # 1 method for generic function "f":
  [1] f(x) in Main at REPL[4]:4

ps: But if I find a way to propose something more concrete, I will post it here, of course.

[MichaelHatherly]

it seems that string is not recognized as a doc entry

Yeah, the parser doesn't recognise arbitrary string macros as docstrings, only normal string literals.

This feature can be added as a DocStringExtensions abbreviation that would just be interpolated into a normal docstring and do "some magic" to track whether it's public or private and possibly do some extra formatting of the docstring as in your first example.

Here's an implementation based on what I wrote back in that linked PR, but just flipped to be an INTERNAL instead of PUBLIC abbrevation:

julia> using DocStringExtensions

julia> struct Internal <: DocStringExtensions.Abbreviation end
       
       const INTERNAL = Internal()
       
       DocStringExtensions.format(::Internal, buf, doc) = println(buf, "**Internal function or structure - interface may change.**\n\n# Extended help\n")
       
       is_internal(doc::Docs.DocStr) = any(x -> isa(x, Internal), doc.text)
is_internal (generic function with 1 method)

julia> """
           f(x) 
       
       $INTERNAL
       
       This function always returns 1
       
       # Example
       
       example of use of f(x)
       """
       f(x) = 1
f

help?> f
search: f fd for fma fld fld1 fill fdio frexp foldr foldl flush floor float first fill! fetch fldmod filter falses finally foreach fldmod1 findmin findmax findall filter!

  f(x)


  Internal function or structure - interface may change.

  ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────

Extended help is available with `??`

help?> ?f
search: f fd for fma fld fld1 fill fdio frexp foldr foldl flush floor float first fill! fetch fldmod filter falses finally foreach fldmod1 findmin findmax findall filter!

  f(x)


  Internal function or structure - interface may change.

  Extended help
  ≡≡≡≡≡≡≡≡≡≡≡≡≡≡≡

  This function always returns 1

  Example
  ≡≡≡≡≡≡≡≡≡

  example of use of f(x)

julia> is_internal(Docs.@ref f(1))
true

Any consuming package or user can then just query any docstring with is_internal to see whether it's internal.

[mortenpi]

With the public keyword, should we consider this no longer really relevant and close this?

X-ref: JuliaLang/julia#50105

[lmiq]

Maybe yes. Actually I feel there is some lack of support for internal-function docstrings in Documenter still (I have been converting them into comments, which is not really ideal), but I guess this is not an issue for DocStringExtensions anyway.

(with the public keyword everything here could be handled by Julia itself, actually, when showing docstrings for internal functions).

[mortenpi]

Yes, I meant that the metadata bit should be handled by the keyword now. Documenter integration is tracked in JuliaDocs/Documenter.jl#1506, and is definitely something we'd want to have.

[lmiq]

Y just saw at the state of julia talk that base will already provide the warning message, in exactly this format. So we definitely can close this.