IRC channel logs
2024-04-26.log
back to list of logs
<dsmith>cow_2001, None of the docstrings go in the manual. They go into the online (inline?) help. <cow_2001>okay, added some texinfo markup to the docstrings. <mwette> the repl ,d will expand some texinfo commands <euouae>I'm disatisfied with the way code is documented in guile lisp <euouae>guild doc-snarf pulls out ;; comments, (ice-9 documentation) works with docstrings but you can't use it for anything but functions <euouae>and it's not clear how to produce well-written documentation. Doxygen, sphinx, rust, haskell do it better. <euouae>way better... am I wrong about this? I don't know <daviid>ArneBab: i don't, though in this particular case, if a module makes its way to guile-lib, i'd vote for (test doctest) - as you know, i resigned from my 'principal maintainer' guile-lib position, so i suggest you post an email, to guile-devel, with a link to 'existing' code, asking for opinionated opinion, (a) whether the module should be added to guile-lib, and if yes, (b) if the api is 'ok' or should be 'reviewed' ... <ArneBab>daviid: I had forgotten that you resigned … sorry. <ArneBab>euouae: you’re right spinx, doxygen, and others do it better. I recently created documentation from docstrings in R and the amount of polish that’s applied by default is mindblowing. For guile you can adapt the texinfo to website method used for Guile, but it’s far from being as convenient as for other documentation tools I used. <euouae>ArneBab: I don't know about R, I haven't used it, but I don't doubt it eitehr. <euouae>Rust has the best doc system I've seen thusfar. <euouae>anyway, Guile's doc system kind of sucks and I'm not sure why. IMHO docstrings are a mistake because they can't be used to document anything but functions. <euouae>Another complaint about Guile: I know it's supposed to be an embeddable language like Lua, but then WHY is it impossible to make GNU Poke work with GNU GDB? Well, you guessed it... it's because both processes load Guile and there's some kind of issue with the GC. ... (w.t.f.?) <euouae>I don't mean to be negative, but I feel that's a huge issue right? <tomnor>Can I attempt to return nothing? The call to display appear to return nothing in the repl <tonyg>tomnor: try returning `*unspecified*` <euouae>what do you mean that you create comments in texinfo? <euouae>I don't quite understand what the point is, you're calling `texi2any --plaintext` over the docstring and output in the *scmtxi texi* buffer, but why? <euouae>nevermind. I missed the explanatory comments. it turns texi ;; comments to docstrings. <euouae>It looks nice however... it is manually activated & requires upkeep to ensure texi matches docstring at all times <euouae>moreover, it doesn't solve the extraction issue (unless you suggest that I can modify it to extract texi comments into other formats outside the document e.g.) <mwette>not a great solution but I can put lists, tables and examples in the docstrings; and a script to pull out all the texinfo comments from a file is very simple <euouae>Well, thanks for pointing it out. I've starred your repository. I'm hoping to not have to write code but if it comes to that, then your solution is on the right track <euouae>since I believe semicolon comments are the way to go about documentation (not docstrings) <cow_2001>oh! there were messages about docstrings here! i should read them all <rlb>wingo: not critical, but wondered if it might be plausible to have Z level cond-expand features, e.g. guile-3.0.11. <mwette>Oh, guile-3.0.11 vs guile-3.0 features <attila_lendvai>context: shepehrd. is whith-exception-handler a continuation barrier, while catch is not? i've converted some catch to with-exception-handler, and now i'm getting an error from fibers. <attila_lendvai>err, wait! if i don't unwind anymore, then it could be some user code on the stack that introduces the continuation barrier, not w-e-h...