# Best practice to document non-API functions

**URL:** <https://discourse.julialang.org/t/best-practice-to-document-non-api-functions/108025>\
**Category:** General Usage\
**Tags:** documentation\
**Created:** [December 25, 2023, 5:18am UTC](https://discourse.julialang.org/t/best-practice-to-document-non-api-functions/108025 "2023-12-25T05:18:52Z")\
**Posts on this page:** 6\
**Page:** 1

<div class="post-metadata">

**Author:** ![David\_Sagan](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/david_sagan/32/33792_2.png) [@David\_Sagan](https://discourse.julialang.org/u/David_Sagan)\
**Post date:** [December 25, 2023, 5:18am UTC](https://discourse.julialang.org/t/best-practice-to-document-non-api-functions/108025/1 "2023-12-25T05:18:52Z")

</div>

I am developing a rather large package that will have a substantial number of functions that are low level and not part of the API. I am new to Julia and am not sure the best way of documenting these. I could write doc strings for them but I have a concern that that would “pollute” the help system in terms a “user” trying to learn about the functions that are in the API. Is this a valid concern? The alternative is to put comments in the file where the doc strings would go. But then I’m concerned about someone helping with coding of the package who might want to use the help system for the non-API functions.

Any guidance is greatly appreciated.

---

<div class="post-metadata">

**Author:** ![jules](https://avatars.discourse-cdn.com/v4/letter/j/41988e/32.png) [@jules](https://discourse.julialang.org/u/jules)\
**Post date:** [December 25, 2023, 8:02am UTC](https://discourse.julialang.org/t/best-practice-to-document-non-api-functions/108025/2 "2023-12-25T08:02:50Z")

</div>

That a docstring means that a nonexported function is public api is only a heuristic, and not a good one in my opinion. Developer docs are valuable and, as you say, you may want to discover these through the repl just like the normal docs.

In future versions of julia, the new `public` keyword will help to discriminate between internal and public nonexported functions [https://github.com/JuliaLang/julia/pull/50105](https://github.com/JuliaLang/julia/pull/50105). Right now, I think you could just add a note that something is internal to its docstring.

---

<div class="post-metadata">

**Author:** ![David\_Sagan](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/david_sagan/32/33792_2.png) [@David\_Sagan](https://discourse.julialang.org/u/David_Sagan)\
**Post date:** [December 26, 2023, 6:38am UTC](https://discourse.julialang.org/t/best-practice-to-document-non-api-functions/108025/3 "2023-12-26T06:38:03Z")

</div>

Very interesting. Thanks for the info.

---

<div class="post-metadata">

**Author:** ![sylvaticus](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/sylvaticus/32/203883_2.png) [@sylvaticus](https://discourse.julialang.org/u/sylvaticus)\
**Post date:** [December 26, 2023, 9:09am UTC](https://discourse.julialang.org/t/best-practice-to-document-non-api-functions/108025/4 "2023-12-26T09:09:47Z")

</div>

Specifically, should be in julia v1.11, around half year from now…

> <https://github.com/JuliaLang/julia/blob/master/NEWS.md>

---

<div class="post-metadata">

**Author:** ![lmiq](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/lmiq/32/18314_2.png) [@lmiq](https://discourse.julialang.org/u/lmiq)\
**Post date:** [December 26, 2023, 9:21am UTC](https://discourse.julialang.org/t/best-practice-to-document-non-api-functions/108025/5 "2023-12-26T09:21:25Z")

</div>

I use this: [Documentation of internals](https://discourse.julialang.org/t/documentation-of-internals/72523)

As a workaround.

---

<div class="post-metadata">

**Author:** ![jishnub](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/jishnub/32/33620_2.png) [@jishnub](https://discourse.julialang.org/u/jishnub)\
**Post date:** [December 26, 2023, 11:59am UTC](https://discourse.julialang.org/t/best-practice-to-document-non-api-functions/108025/6 "2023-12-26T11:59:17Z")

</div>

> [@jules](#):
>
> That a docstring means that a nonexported function is public api is only a heuristic, and not a good one in my opinion

Worth noting that Julia doesn’t follow the convention that all methods with docstrings are public. In Julia Base, only the types/methods that are explicitly included in the documentation are public. Internal types and methods may have docstrings, but just because a docstring exists doesn’t imply that the name is public. Version v1.11 of Julia would make this more explicit, with a warning about bindings being internal.