# Documenting nested functions

**URL:** <https://discourse.julialang.org/t/documenting-nested-functions/129708>\
**Category:** Internals & Design\
**Tags:** question, documentation, potential-bug, docstring\
**Created:** [June 6, 2025, 4:58pm UTC](https://discourse.julialang.org/t/documenting-nested-functions/129708 "2025-06-06T16:58:55Z")\
**Posts on this page:** 3\
**Page:** 1

<div class="post-metadata">

**Author:** ![maxwell3025](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/maxwell3025/32/217233_2.png) [@maxwell3025](https://discourse.julialang.org/u/maxwell3025)\
**Post date:** [June 6, 2025, 4:58pm UTC](https://discourse.julialang.org/t/documenting-nested-functions/129708/1 "2025-06-06T16:58:55Z")

</div>

I’m currently working on a project and I came across an issue with using nested functions.  
In particular, I have a nested function that I want to document, and I am getting a warning about “replacing docs”.  
This seems to only appear when the outer function is defined in a particular way.

The relevant code is in [Docs.jl](https://github.com/JuliaLang/julia/blob/release-1.11/base/docs/Docs.jl#L242-L243).

Minimal example:

```julia
module Mod
  """
  This is foo
  """
  foo() = begin
    """
    This is bar
    """
    function bar()
      println("world")
    end
    println("hello")
    bar()
  end
end

Mod.foo()
Mod.foo()

# hello
# world
# ┌ Warning: Replacing docs for `Main.Mod.bar :: Tuple{}` in module `Main.Mod`
# └ @ Base.Docs docs/Docs.jl:243
# hello
# world

```

Without outer function def:

```julia
module Mod
  """
  This is foo
  """
  function foo()
    """
    This is bar
    """
    function bar()
      println("world")
    end
    println("hello")
    bar()
  end
end

Mod.foo()
Mod.foo()

# hello
# world
# hello
# world

```

Is this behavior a bug? It seems like a fairly common use case, and seeing as the existing `Docs.jl` code suppresses the warning in other cases, it seems like nested functions would be a reasonable case to suppress the warning.

Also, why does the definition of the outer function affect the behavior? I thought that the 2 definition forms were identical.

---

<div class="post-metadata">

**Author:** ![nsajko](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/nsajko/32/221187_2.png) [@nsajko](https://discourse.julialang.org/u/nsajko)\
**Post date:** [June 8, 2025, 5:37pm UTC](https://discourse.julialang.org/t/documenting-nested-functions/129708/2 "2025-06-08T17:37:05Z")

</div>

> [@maxwell3025](#):
>
> ```julia
> foo() = begin
> 
> ```

Works fine if you replace `begin` with `let`. The difference between `let` and `begin` is that `let` introduces a scope.

I’m not sure if this is a bug or not (I suppose it is), but in any case I’d recommend always using the `function` syntax for defining a method. That way you get more granular source line info, relevant for code coverage, stack traces, debugging, etc.

---

<div class="post-metadata">

**Author:** ![Tamas\_Papp](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/tamas_papp/32/25949_2.png) [@Tamas\_Papp](https://discourse.julialang.org/u/Tamas_Papp)\
**Post date:** [June 9, 2025, 6:15am UTC](https://discourse.julialang.org/t/documenting-nested-functions/129708/3 "2025-06-09T06:15:53Z")

</div>

> [@nsajko](#):
>
> The difference between `let` and `begin` is that `let` introduces a scope.

But the method definition `foo() = ` should introduce a scope already.

I agree that for multiline functions `function` is preferred, nevertheless this may be a bug. It is worth reporting, especially since @maxwell3025 isolated a nice concise MWE.