Allow instance docstrings

Duplicates improvement made to Base's `Enum`s: JuliaLang/julia#61955

Author: jmert

Project.toml

@@ -7,8 +7,9 @@ version = "0.1.9"
 julia = "1"
 
 [extras]
+Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a"
 Serialization = "9e88b42a-f829-5b0c-bbe9-9e923198166b"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [targets]
-test = ["Serialization", "Test"]
+test = ["Markdown", "Serialization", "Test"]

src/BitFlags.jl

@@ -259,9 +259,20 @@ function _bitflag_impl(__module__::Module, __source__, scope::Union{Symbol, Noth
     maskzero, maskother = false, zero(basetype)
     i = oneunit(basetype)
     two = oneunit(basetype) + oneunit(basetype)
+    docs = Dict{Symbol,Expr}()
 
     for s in syms
         s isa LineNumberNode && continue
+        if isexpr(s, :macrocall, 4) && (
+            sa = s.args[1];
+            sa === Symbol("@doc") || sa == GlobalRef(Core, Symbol("@doc"))
+        )
+            doc = s
+            doc.args[3] = Core.eval(__module__, doc.args[3])  # evaluates string macros, e.g. md"doc string"
+            s = s.args[4]
+        else
+            doc = nothing
+        end
         if s isa Symbol
             if (i == typemin(basetype)) && (maskother & typemax(basetype) != 0)
                 throw(ArgumentError("overflow in value \"$s\" of BitFlag $typename"))
@@ -303,6 +314,9 @@ function _bitflag_impl(__module__::Module, __source__, scope::Union{Symbol, Noth
             lo = min(lo, i)
             hi = max(hi, i)
         end
+        if doc !== nothing
+            docs[sym] = doc
+        end
         i = iszero(i) ? oneunit(i) : two*i
     end
 
@@ -322,7 +336,12 @@ function _bitflag_impl(__module__::Module, __source__, scope::Union{Symbol, Noth
     @inbounds for ii in 1:length(names)
         sym, val = names[ii], values[ii]
         instances[ii] = :(bitcast($etypename, $val))
-        flagconsts[ii] = :(const $(esc(sym)) = bitcast($etypename, $val))
+        flagex = :(const $(esc(sym)) = bitcast($etypename, $val))
+        if haskey(docs, sym)
+            docs[sym].args[4] = flagex
+            flagex = docs[sym]
+        end
+        flagconsts[ii] = flagex
     end
     namemap = NamedTuple{(names...,)}((values...,))
 

test/runtests.jl

@@ -1,11 +1,15 @@
 using BitFlags
-using Test, Serialization
+using Markdown
+using Serialization
+using Test
 
 # workaround for https://github.com/JuliaLang/julia/issues/54664
 function extractdoc(doc)
     # On v1.11 without REPL loaded, the @doc macro returns a Base.Docs.DocStr object;
     # extract the stored string from the object.
-    doc isa Base.Docs.DocStr && return doc.text[1]
+    if doc isa Base.Docs.DocStr
+        doc = !isnothing(doc.object) ? doc.object : first(doc.text)
+    end
     # Otherwise, assume we get something like a Markdown.MD object and just turn it into
     # a string. (Strip trailing newline for consistency with above form.)
     return strip(string(doc))
@@ -104,11 +108,19 @@ end
 
 #@testset "Documentation" begin
     # docstring literal
-    """My Docstring""" @bitflag DocFlag1 docflag1a
+    """My Docstring""" @bitflag DocFlag1 begin
+        """first flag"""
+        docflag1a
+    end
     @test extractdoc(@doc(DocFlag1)) == "My Docstring"
+    @test extractdoc(@doc(docflag1a)) == "first flag"
     # docstring macro for non-string literals
-    @doc raw"""Raw Docstring""" @bitflag DocFlag2 docflag2a
+    @doc raw"""Raw Docstring""" @bitflag DocFlag2 begin
+        @doc md"""**second flag**"""
+        docflag2a
+    end
     @test extractdoc(@doc(DocFlag2)) == "Raw Docstring"
+    @test extractdoc(@doc(docflag2a)) == "**second flag**"
 #end
 
 #@testset "Type properties" begin