The issue is that you want to have all code documentation show up in REPL. In the GoDoc approach, this might require an explicit "build" step -- which is a non-trivial cost in usability.
-- John On Aug 25, 2014, at 3:01 PM, Job van der Zwan <[email protected]> wrote: > 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.
