« first day (1788 days earlier)      last day (3159 days later) » 

11:02 PM
@elyse the documentation isn't bad at all
 
user1804599
Right.
 
most opensource projects don't feature a good doxygen documentation (if doxygen is your highest expectation)
 
user1804599
But that's because what doesn't exist can't be bad.
 
doxygen is cool
everybody should doxygen
 
i can’t recall a time where i found myself happy reading a doxygen documentation
 
11:13 PM
When I tried to read LLVM docs all I saw was autogenerated doxygen output garbage
not even a \brief or \details.
just an API dump
 
user1804599
yay it works
 
user1804599
std::error_code ec;
llvm::raw_fd_ostream stream("build/a.ll", ec, llvm::sys::fs::OpenFlags::F_RW);
m.print(stream, nullptr);
std::system("C:\\Users\\elyse\\llvm-install\\bin\\llc -filetype=obj build\\a.ll");
std::system("gcc -IC:\\Users\\elyse\\gc-install\\include -LC:\\Users\\elyse\\gc-install\\lib -lgcmt linert\\*.c build\\a.obj -o build\\a");
std::system("build\\a");
 
Doxygen is poorly suited to the documentation you usually need the most when dealing with a new library (or whatever), but for what it's really intended to do, it can work reasonably well. To be more specific: if you need a (slightly) expanded version of of the documentation a decent IDE will pop up based only on the function declaration, telling you want parameters to pass and such, Doxygen can work reasonably well. For documentation of higher level concepts and such...not so much.
 
facebook's react API has really nice docs
I wonder what they used to write them
 
just saw them
that's definitely sphinx
or jekyll
either or
alright I looked at the source
it's jekyll
 
11:17 PM
cool
 
are u a wizard
 
I think Im going to write my docs (never) when I finish my lib (lol) with madoko.net
 
@LucDanton obv
I use Sphinx for my docs now.
 
yeah I saw
I tried my hand at documenting a Python thing, very fancy
 
@LucDanton I'm a wizard under a sheet (but no, not KKK).
 
11:19 PM
@LucDanton ikr. autodoc to boot.
 
sphinx isn't helpful with generating documentation though for c++ right? its just for writing stuff with something similar to MD
 
it's fine
 
what does 'its fine' mean
 
@Prismatic I think you may have some misconceptions here.
 
I want something that parses sources and then creates a template.
Then you fill in that template with real words.
 
11:20 PM
it looks like this
what's wrong with that?
it's pretty adequate.
 
not very webscale
good morning
 
morning
 
fuck this werewolf
 
@Rapptz thats dope if its autogenerated
 
it isn't
I wrote it all by hand
 
11:21 PM
I wonder how many people find documentation useful ...
 
I can't tell if you're being sarcastic
 
I'm serious.
 
Documentation is half (if not more) of the success of a project
 
Okay so then sphinx is just a glorified markdown thing
 
11:22 PM
I want an annotation system on C++ sources where I can write MOST of the docs of the project.
 
@Prismatic Nope.
 
Not really.
 
2 mins ago, by Luc Danton
@Prismatic I think you may have some misconceptions here.
 
Or something that at least updates and checks my documentation's skeletons
For like parameters and stuff.
 
upgraded to 'definitively'
 
11:22 PM
Care to clear up my misconceptions?
 
First of all it's restructuredText.
 
A successful project just runs without any problem
 
@Prismatic Any doc tool will use some form of markup. That’s not the important part.
 
documentation or not
 
11:23 PM
@Prismatic It provides a way to index the project.
 
also sales well ...
 
So you can do e.g. :func:`coolfunc` to reference the function.
Theme support that is 1000000000000000000000x easier than Doxygen.
have you tried editing Doxygen output?
 
not seriously; ive played around with changing colors and stuff like that
 
It's a total pain.
Doxygen is very opinionated.
 
user1804599
godoc is the best.
 
11:25 PM
theme support is orthogonal to a code documentation generator imo
 
It makes documenting heavy meta-programming libs a total mess.
Not for C++.
Doxygen is strictly OOP-land.
It doesn't understand other valid paradigms for C++.
So your output ends up looking like ass.
 
When you say func:coolfunc or whatever, does that mean you're actually referring to a specific source file?
 
Presentation is important in documentation.
 
So if I change the name of the function, the documentation will automatically update? I'm just finding it hard to understand what sphinx does specific to code for c++
 
Hard to describe I think.
All of this is manual.
Like what I'm writing.
I'm writing the declarations and stuff.
 
11:27 PM
That's a bit of a deal breaker for me.
 
@Rapptz There's no documentation tool that can understand how to properly deal with templates
 
I want something that at least can handle updating declarations.
 
Sphinx can handle templates just fine.
 
And then, of course, warning / smacking me over the head if I don't go update my docs.
Guess that's what lucdoc™ is going to have to do...
 
Well due to limitations in reST you have to do :func:`templated_func\<T>`.
but it understands templated stuff just fine
 
11:28 PM
You just said eveyrthing you write is manual. So what I'm taking away from this is that sphinx has specific formatting when you manually add template documentation
 
not really?
just do <T> like you would in C++-land.
 
> 5 - 8 day free shipping, tells you its gonna arrive next week
 
Not exactly specific-formatting.
 
> estimated delivery time: in 2 days
Pffff.
 
Alright, I think I'll give up trying to understand what sphinx is
 
11:29 PM
Scaretactics ain't getting me!
 
Rapptz’ example is just one page.
 
Yeah... there are multiple pages.
 
It’s not the only way you have to use Sphinx.
 
So you can write your intro, tutorials, etc.
All in reST.
And reference the code through the multiple pages.
it's not like doxygen where you just dump API
granted, there's \page & co.
But having worked with them they are pretty bad.
 
Browse around and have a look at the source, it should be instructive.
 
11:31 PM
Anyway there's an autodoc thing for Sphinx for C++.
It's called Breathe.
 
Any experience?
 
It uses Doxygen-syntax.
Nope.
 
._. why
I’m already annoyed to have to deal with reST in addition to the various flavours of Markdown, and reST is really good at its job.
 
lol I'd honestly just like something like autodoc in python
I'm wondering how hard it'd be to write a thing in python using the libclang python wrapper thing and make a sphinx plugin
 
21 hours ago, by Rapptz
what should I work on in C++
dang not applicable
 
11:34 PM
ikr
damn you python
so easy to use and shit
peek at libclang
wait does libclang remove comments
that'd make it hard wouldn't it
2
 
no clue
 
I keep thinking there should be a www.rest.com that supports formatting reST via a REST API...
 
this thing from 2012 says that they don't give you comments
but I think doxygen uses libclang now
so it might be outdated
 
that’s almost from a century ago
 
11:38 PM
autodoc for python isn't even that special
it just injects the __doc__ to the .rst file.
yet somehow it's insanely helpful
 
So far all I have is autodoc pages.
 
user1804599
@Rapptz it has APIs for extracting /** ... */ comments.
 
@Rapptz careful there, you're stepping into starrable territory
 
wouldn't want that
@elyse could you point me in the right direction there?
 
Speaking of reST I actually used napoleon to use the Google style.
 
muh dick
does it strip the leading * too?
 
nnnnnnn I wish I knew how qt processes certain updates on the render thread. It seems so difficult
 
well here I am with a new python project
but not a new C++ project
THANKS
@LucDanton hm?
 
For Python docstrings.
 
11:44 PM
Wow that's weird.
I just use :param x: Info about param here etc
 
Yeah I didn’t like how that looked, too busy.
 
@elyse Oh GOD the backslashes
 
> This event appears to be bugged as recently as June 2015.
fuck
 
let's see how hardcore libclang is
wish me luck friends
amount of docs on libclang: 0
all I see are blog posts from not-2015.
 
11:52 PM
gl mate
 
aren't you one of those LLVM nerds
you should help :D
 
nah, i was spoonfed by @Puppy
:)
 
the actual file itself seems fairly decently documented
oh wow
the lib they distribute in pip is like a million years old
how nice of them
> Playing with libclang · (-: - Gaëtan Lehmann's Blog
lewd
 

« first day (1788 days earlier)      last day (3159 days later) »