tryte has quit [Read error: Connection reset by peer]
nicoo has quit [Read error: Connection reset by peer]
cantstanya has quit [Read error: Connection reset by peer]
azot has quit [Remote host closed the connection]
andreas303 has quit [Read error: Connection reset by peer]
mxns has quit [Ping timeout: 260 seconds]
andreas303 has joined #ocaml
tryte has joined #ocaml
nicoo has joined #ocaml
azot has joined #ocaml
cantstanya has joined #ocaml
dhil has quit [Ping timeout: 264 seconds]
mxns has joined #ocaml
neiluj has quit [Ping timeout: 256 seconds]
pkl has quit [Ping timeout: 265 seconds]
mxns has quit [Ping timeout: 246 seconds]
arecaceae has quit [Remote host closed the connection]
arecaceae has joined #ocaml
Tuplanolla has quit [Quit: Leaving.]
Haudegen has quit [Ping timeout: 272 seconds]
<d_bot>
<Chum> what is the *.* for
<d_bot>
<Chum> 4 +. 3 = 7
<sleepydog>
(+.) is the operator for adding floating-point numbers, (+) is for adding integers
<d_bot>
<Chum> thank you!
mxns has joined #ocaml
mxns has quit [Ping timeout: 272 seconds]
<d_bot>
<Chum> what does the star operator mean
<d_bot>
<Chum> i keep thinking they are talking about pointer
<sleepydog>
star is multiplication. (!) is used for dereferencing
<d_bot>
<Chum> ?
<d_bot>
<Chum> So how Can a function type be int * int *
<sleepydog>
ah, you're talking about in types. there it is used for tuples
_whitelogger has joined #ocaml
borne has quit [Ping timeout: 264 seconds]
mxns has joined #ocaml
mfp_ has quit [Ping timeout: 256 seconds]
mxns has quit [Ping timeout: 240 seconds]
borne has joined #ocaml
mxns has joined #ocaml
zebrag has quit [Quit: Konversation terminated!]
zebrag has joined #ocaml
mxns has quit [Ping timeout: 264 seconds]
zebrag has quit [Quit: Konversation terminated!]
motherfsck has quit [Ping timeout: 265 seconds]
mxns has joined #ocaml
motherfsck has joined #ocaml
mxns has quit [Ping timeout: 264 seconds]
_whitelogger has joined #ocaml
waleee-cl has quit [Quit: Connection closed for inactivity]
vicfred has quit [Quit: Leaving]
borne has quit [Ping timeout: 260 seconds]
borne has joined #ocaml
ArthurStrong has joined #ocaml
borne has quit [Ping timeout: 240 seconds]
mxns has joined #ocaml
mxns has quit [Ping timeout: 246 seconds]
andreas303 has quit [Remote host closed the connection]
andreas303 has joined #ocaml
mbuf has joined #ocaml
mxns has joined #ocaml
decentpenguin has quit [Quit: ZNC crashed or something]
decentpenguin has joined #ocaml
ArthurStrong has quit [Ping timeout: 264 seconds]
mxns has quit [Ping timeout: 240 seconds]
mxns has joined #ocaml
mxns has quit [Ping timeout: 264 seconds]
_whitelogger has joined #ocaml
mxns has joined #ocaml
mxns has quit [Ping timeout: 264 seconds]
Tuplanolla has joined #ocaml
borne has joined #ocaml
borne has quit [Ping timeout: 260 seconds]
azot has quit [Remote host closed the connection]
borne has joined #ocaml
olle_ has joined #ocaml
borne has quit [Quit: WeeChat 3.0]
azot has joined #ocaml
leah2 has quit [Ping timeout: 272 seconds]
<d_bot>
<Drup> @ostera interesting blog post. One remark I could make is that you tend to conflate in the text "documention" with "design of the API", and you shouldn't.
<d_bot>
<Drup> Otherwise, well, it's something that I'm particularly aware of, given the style of libraries I write >_>
ArthurStrong has joined #ocaml
leah2 has joined #ocaml
olle_ has quit [Ping timeout: 240 seconds]
nicoo has quit [Ping timeout: 268 seconds]
nicoo has joined #ocaml
arecaceae has quit [Remote host closed the connection]
arecaceae has joined #ocaml
mfp_ has joined #ocaml
Haudegen has joined #ocaml
mxns has joined #ocaml
mxns has quit [Ping timeout: 272 seconds]
ewd has joined #ocaml
dhil has joined #ocaml
waleee-cl has joined #ocaml
dhil has quit [Ping timeout: 240 seconds]
zebrag has joined #ocaml
ArthurStrong has quit [Quit: leaving]
zebrag has quit [Quit: Konversation terminated!]
zebrag has joined #ocaml
sz0 has joined #ocaml
dhil has joined #ocaml
Haudegen has quit [Quit: No Ping reply in 180 seconds.]
Haudegen has joined #ocaml
zebrag has quit [Quit: Konversation terminated!]
zebrag has joined #ocaml
neiluj has joined #ocaml
tryte has quit [Ping timeout: 268 seconds]
tryte has joined #ocaml
bartholin has joined #ocaml
mxns has joined #ocaml
sagax has joined #ocaml
zebrag has quit [Quit: Konversation terminated!]
zebrag has joined #ocaml
oriba has joined #ocaml
osa1_ has joined #ocaml
osa1 has quit [Ping timeout: 246 seconds]
olle_ has joined #ocaml
<d_bot>
<ostera> thanks, and i agree that it could use more editing to clear up the language / narrative 🙂 I'm trying to use the mailing list as more of a "draft idea, shared early" sort of thing
<sleepydog>
sometimes i wonder if you should get someone else to document your code. because you know the code so well you end up documenting the wrong things
osa1 has joined #ocaml
<sleepydog>
like documenting how something is implemented instead of how to use it
osa1_ has quit [Ping timeout: 272 seconds]
zebrag has quit [Quit: Konversation terminated!]
zebrag has joined #ocaml
boxscape has joined #ocaml
<companion_cube>
sometimes it does make sense, I think
<companion_cube>
if you've learnt a library recently, you're probably in the best position to document it
<companion_cube>
or to write tutorials, at least
boxscape has quit [Quit: Connection closed]
olle_ has quit [Ping timeout: 264 seconds]
<d_bot>
<Drup> It's a good idea in theory that doesn't really work in practice. Most people do not enjoy documenting stuff and in any case it's a huge amount of efforts, so you are basically delegating the annoying job. That's why saying "Yes, I know it's badly documented, we know, contributions welcome ;););)" is just a condescending and obnoxious way of saying "I don't care/I'm lazy"
<companion_cube>
ah well, I'm not saying you should rely on that
<companion_cube>
but if no one contributes doc, your doc will probably be hard to grok for beginners
<oriba>
sounds a bit like an excuse for the developers to write the documentation...
<oriba>
let the users do the work?
<oriba>
wtf
<oriba>
to write documentation and don't see it as annoying,m is an attitude, that can be learnt
<oriba>
and to go back to the "beginners mind" can also be learnt
<oriba>
in my new job I have to maintain 20years old legacy Perl code without documentation and without tests.
<companion_cube>
I disagree with that last point
<oriba>
So when I read such things, it makes me angry
<companion_cube>
how do you learn how to see your project with fresh eyes?
<companion_cube>
oriba: you're reading too much into what I say
<oriba>
do meditation, let the code rot for some weeks, go back to it
<companion_cube>
lol
<companion_cube>
as if you just forget in a few weeks
<oriba>
it can be learnt. Just do it like: "assue I don't know how to use it"
<oriba>
Or do it like: "If I want to use it, what do I need?"
<oriba>
and write it down
<oriba>
also the documentatuion itself can rot for a while... and come back later
<oriba>
it's a process.
<oriba>
documentation can also be refactored
<oriba>
Then, when oyu go back to it, just follow it step by step
<oriba>
if it does not work out, you missed something
<sleepydog>
I didn't mean to say you shouldn't document your code. I mean what makes total sense to you can be complete gibberish to someone who didn't write your code, or is a beginner in the language
<companion_cube>
oriba: the hard part is the new concepts
<oriba>
then give it to beginners and let them vote thumb up or down
<oriba>
I agree that it often is bad documented.
<companion_cube>
and do some A/B testing!
<companion_cube>
and don't forget to add ads because google does it
<oriba>
I have found a lot of ocaml code that was bad documented (especially the concepts, yes)
<companion_cube>
you cn't just forget the concepts, that's the hard part to explain
<companion_cube>
just saying what each function does it comparatively easy
<oriba>
OCaml has the big advantage that you can ask ocaml for the types (or look into the mli-files)
<oriba>
A tool that shows the hierarchy of types would be helpful
<oriba>
creating an image from the dependencies can help a lot
<oriba>
ocamldep-output to dot and then you have an overview
<oriba>
if one function needs output of another function and this is given by the types ( not anything string ;-) ), then you have a hierarchy of the types. Make an image from this -> helpful
<sleepydog>
i think sorting your declarations sufficiently can get you ~75% of the way there
<sleepydog>
and using type aliases
<oriba>
the problem with some official documenting tools for ocaml was, that reordering of th documentation was not possible.
<oriba>
I think there is a project working on these issues
<oriba>
recently I was looking for possibilities to use Ocaml for image processing. OWL was recommended.
<oriba>
even though it is much documentation, and also very detailed, the disadvantage is: too much, and not easy to find what you need
vicfred has joined #ocaml
neiluj has quit [Remote host closed the connection]
<oriba>
The one extreme: no documnentation. The other: much dicumentation, but hard to find the docxument that gets to the point
<oriba>
So I picked up some old C-code and write my tool in C now.
<oriba>
I already had written a libjpeg-wrapper in C, so I added the math now (not complete so far, but close)
<sleepydog>
if you had found an example that was close enough to what you wanted to do, would you have gone with owl?
<oriba>
Maybe yes
<oriba>
examples would be helpful
<oriba>
now I use C and I'm fine with it.
<oriba>
yesterday I thought, maybe using OCaml together with C.
<oriba>
but I just want to finish it in C, not again change anything.
<sleepydog>
I find OCaml quite easy to use with C. even without helpers like cstruct
<oriba>
I did that some years ago. It was ok.
<oriba>
But I can't estimate, where speed-bottlenecks would pop up
<oriba>
And I just want to use the tool, not writing a PhD on C-with-OCaml ;-)
<companion_cube>
obviously C tools have much better documentation
<companion_cube>
/s
<oriba>
I olny used libjpeg (so I have aproblem with png etc).
<oriba>
It comes with a txt-file as documentation.
<sleepydog>
documentation is less important when there is a huge corpus of code for you to copy-paste, i think
<oriba>
But my wrapper helped my a lot, so I didn't needed to read the docs again.
<oriba>
imo documentation of code is more important than tests.
<sleepydog>
i think i agree with that
<oriba>
:-)
zebrag has quit [Quit: Konversation terminated!]
zebrag has joined #ocaml
mxns has joined #ocaml
elfring has joined #ocaml
bartholin has quit [Quit: Leaving]
<companion_cube>
so you're mad that people might ask newcomers to contribute docs, but you're ok with stack-overflow as docs
mbuf has quit [Quit: Leaving]
<oriba>
??
<companion_cube>
to be fair that's sleepydog's point, sorry.
<sleepydog>
i don't know that i had a point. just rambling :)
<oriba>
Sometimes you find code that has examples in the (minimalistic) documentation. You are happy to have that example, copy it from the *.md/*.html and it just don't work. So, it was not tested. Why not providing a running example, and point to it in the docs, instead of putting untested code as example in the documentation, that does not run? Putting non-working examples in the docs is very annoying. If the devlelopers can't
<oriba>
provide a running example, will the code work at all? Is it the right attidtude to ask other people to provide running examples?
<oriba>
Maybe they should just reqrite the code, not just help with docs?
<oriba>
Maybe just remove the entire repo?
<sleepydog>
heh, i'm definitely guilty of the broken examples thing. usually happens when i write how i want something to work before i implement it and forget to change it later :)
mxns has quit [Ping timeout: 260 seconds]
<sleepydog>
i think the context matters here. if you're getting paid for your work you should document it well. if you're just sharing something you wrote and thought would be useful, even if you don't have the energy to document it, i think that's fine
boxscape has joined #ocaml
<sleepydog>
although i think as you said, oriba, you can cultivate an attitude that documentation should not be an annoying task
<oriba>
I said something like that above... do you want to emphasize that?
<sleepydog>
> to write documentation and don't see it as annoying,m is an attitude, that can be learnt
<oriba>
yes
<oriba>
it's easier when you have encountered not to understand the code, that you have written once :-)
<oriba>
that is a motivator
<sleepydog>
yea, i've definitely had the internal monologue, "who wrote this piece of ... oh"
<oriba>
also it saves time, just to look at the docs
<oriba>
instead of reeingineering again and again
<oriba>
hehe
<oriba>
documentation can also be seen as information hiding. Why to read the code? The code is the implementation, the docs are the signature/api
<oriba>
so imo the necessity to read the code to get things running is bad
<companion_cube>
no one is arguing for that
<companion_cube>
but most people write .mli files
<companion_cube>
the problem is docs that go beyond that
zebrag has quit [Quit: Konversation terminated!]
zebrag has joined #ocaml
<oriba>
"no one is arguing for that" flashback from the work ;-)
<oriba>
"the problem is docs that go beyond that" yo you see documentation as a problem, hmhhhh ;-)
<oriba>
"we have a problem (documentation) - how can we get rid of the problem?" -> "rm -rf docs"
<oriba>
problem solved ;-)
<oriba>
so, maybe "problem" is the problem here
<companion_cube>
I mean, if you don't write .mli files, good for you I guess
<companion_cube>
but in OCaml it's pretty easy to do
<companion_cube>
it's like level 0 of documentation
<companion_cube>
writing docstrings also helps, of course
leah2 has quit [Ping timeout: 272 seconds]
<oriba>
mli-files are a great thing. I did not appreciated it in the beginning, when starting with OCaml. But they can be very helpful in a log of ways.
<oriba>
s/log/lot/
<oriba>
it's also great to have ocamlc -i compare that with the Perl-nightmare that I have at work these days... wtf
<sleepydog>
on the topic of docstrings, i have a menhir/ocamllex parser that currently discards comments and i'm wondering what's a good approach to associate a comment block with the nearest expression
<sleepydog>
i'm looking at how ocaml/ocaml does it
<sleepydog>
err, the ocaml compiler, that is
<companion_cube>
Ocaml doesn't preserve comments in the AST
<companion_cube>
only docstrings
<oriba>
not sue what you mean, but there is (* *) vs. /* */ in the lexers
<companion_cube>
(which are translated to AST attributes)
<sleepydog>
how does it associate a docstring with an expression? is that done during lexing?
<companion_cube>
good question, because whitespace does change stuff there (there's even a warning if it's ambiguous)
<sleepydog>
i see there's a DOCSTRING token with location data in it
<sleepydog>
i found a thread on discuss talking about just providing a "pop most recent comment" function in the lexer that the parser could call, but wanted to find an example before i did it wrong
<companion_cube>
olk so it's a lexer trick, nice
<sleepydog>
yea, i like that idea. maybe i will just go ahead and do that
<oriba>
not the documentation is the problem, the tools have a problem supporting the developers in documenting the code
<sleepydog>
do you think so? i think the tooling for documenting OCaml is pretty good. for consuming the docs i think a central odoc site would be *awesome*, though
boxscape has quit [Quit: Connection closed]
boxscape has joined #ocaml
<oriba>
this was just my impression, when reading "so it's a lexer trick". But I have my head in my C-code and did not followed your discussion really.
<oriba>
odoc is better than ocamldoc I guess
<oriba>
didnt used it
<oriba>
thought it is just in early stage
<oriba>
will it become part of the official Ocaml distribution one day?
<sleepydog>
i don't know, maybe. i don't think it supports all the output formats that ocamldoc supports
<oriba>
can it change the order of sections in the documentation?
<oriba>
reordering the code to have the docs in the right order is a bit annoying.
<oriba>
ocamlnet had that problem, last time I last asked the developer of it
leah2 has joined #ocaml
<oriba>
that was ocamldoc at that time
<sleepydog>
i don't think so. at least it doesn't do that by default
zebrag has quit [Quit: Konversation terminated!]
zebrag has joined #ocaml
olle_ has joined #ocaml
mxns has joined #ocaml
mxns has quit [Ping timeout: 272 seconds]
boxscape has quit [Quit: Connection closed]
<d_bot>
<EduardoRFS> There is a list of changes that is going to happen for OCaml 5.0? Maybe we can disable flat float array by default?
boxscape has joined #ocaml
mxns has joined #ocaml
mxns has quit [Ping timeout: 256 seconds]
zebrag has quit [Quit: Konversation terminated!]
zebrag has joined #ocaml
leah2 has quit [Ping timeout: 264 seconds]
arecaceae has quit [Remote host closed the connection]