Re: [julia-users] Re: Does Julia have something similar to Python's documentation string?
On Tuesday, 26 August 2014 00:04:41 UTC+2, John Myles White wrote: 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 I assume you talking about GoDoc as a tool? In case you are referring to comments as the source of documentation instead of docstrings: I assume comments are now simply discarded during compilation, making it impossible to use them for documentation, but if that could be changed they should be just as valid as the format for documentation, right?
Re: [julia-users] Re: Does Julia have something similar to Python's documentation string?
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.
Re: [julia-users] Re: Does Julia have something similar to Python's documentation string?
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 j.l.vanderz...@gmail.com 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.
[julia-users] Re: Does Julia have something similar to Python's documentation string?
Any plans? Discussions on Github worth reading through? I personally am really charmed by the godoc http://blog.golang.org/godoc-documenting-go-code approach - could something like that work for Julia? (so figuring out a sensible idiomatic way to document functions and modules that makes the documentation easy to read in plaintext, but also easy to be turned into pretty formatted documentation by tools) On Sunday, 24 August 2014 23:07:30 UTC+2, Ivar Nesje wrote: Not yet.
[julia-users] Re: Does Julia have something similar to Python's documentation string?
Happy reading: https://github.com/JuliaLang/julia/issues/3988 :) On Sunday, August 24, 2014 5:03:04 PM UTC-5, Job van der Zwan wrote: Any plans? Discussions on Github worth reading through? I personally am really charmed by the godoc http://blog.golang.org/godoc-documenting-go-code approach - could something like that work for Julia? (so figuring out a sensible idiomatic way to document functions and modules that makes the documentation easy to read in plaintext, but also easy to be turned into pretty formatted documentation by tools) On Sunday, 24 August 2014 23:07:30 UTC+2, Ivar Nesje wrote: Not yet.
Re: [julia-users] Re: Does Julia have something similar to Python's documentation string?
I really like godoc – that's basically what I want plus a convention that the doc strings are markdown. On Aug 24, 2014, at 6:03 PM, Job van der Zwan j.l.vanderz...@gmail.com wrote: Any plans? Discussions on Github worth reading through? I personally am really charmed by the godoc approach - could something like that work for Julia? (so figuring out a sensible idiomatic way to document functions and modules that makes the documentation easy to read in plaintext, but also easy to be turned into pretty formatted documentation by tools) On Sunday, 24 August 2014 23:07:30 UTC+2, Ivar Nesje wrote: Not yet.
