Giter VIP home page Giter VIP logo

Comments (7)

mortenpi avatar mortenpi commented on July 22, 2024

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?

from docstringextensions.jl.

lmiq avatar lmiq commented on July 22, 2024

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.

from docstringextensions.jl.

MichaelHatherly avatar MichaelHatherly commented on July 22, 2024

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.

from docstringextensions.jl.

Related Issues (20)

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.