On Monday, 25 August 2014 01:23:26 UTC+2, Jason Knight wrote: > Happy reading: https://github.com/JuliaLang/julia/issues/3988 :) >
Thanks, that was indeed interesting :) On Monday, 25 August 2014 01:43:11 UTC+2, Stefan Karpinski wrote: > > I really like godoc – that's basically what I want plus a convention that > the doc strings are markdown. > >From what I understand of the discussion linked above, the suggested approach is a @doc macro followed by a string, making documentation part of compiling the code, correct? The godoc approach is different in two ways: documentation is not part of the runtime but a separate tool that parses Go source files, and it extracts documentation from the *comments*, based on where they are placed. The former part of the difference is just a consequence of how Go and Julia are used differently, so probably not that relevant, but Go's approach of using comments to indicate documentation sounds more sensible to me - documentation is what comments are for, are they not? Then why not suggest an idiomatic way to use the comments, and make a tool/the Julia runtime capable of extracting documentation information from that structure? Mind you, I don't use Python so perhaps this is also a personal matter of not being used to docstrings.
