Hi~ On Fri, Nov 7, 2014 at 2:40 PM, Jeff Grimshaw <jeffrey.w.grims...@gmail.com> wrote:
> Thanks for this raster. > > I'm not active on the list so you might not remember, but back in May I > signed > up to chip away at the 7000+ warnings that are (still!) generated from > "make doc" on > the root. I made some headway with eina but after a few commits, life > intruded and > I got discouraged. > > This email has brought me back! :-) > > Anyway, here's my 2-cents, in no particular order. > > For licencing, I've always liked the BSD 2-clause license. It's simple. > > Developers, especially the core devs, should not be maintaining > documentation. > It's a chore, it's not your core competency and you have better > things to do. Leave it for people who enjoy doing it. If you make it easy > to do, > they will show up. > > All the API reference documentation should be generated from comments in > the > header files, similar to what's done today. This keeps the API doc closer > to the code > and makes it more likely to be updated as needed. All the other > documentation should > NOT be in the header files. See Eina.h for the anti-pattern. Expository > documentation > should be a first class citizen and have its own source files from which it > is generated. > I tend to agree with this idea that the core API reference should be linked to the code, aka the EO files. But this means we need to be able to sync between the wiki markdown and the EO documentation from time to time. Syncing back from the Wiki to the EO files sounds hard to do though. The API ref doc that is not EO stuff should mostly come from Eina which is quite C specific, so other language bindings may not be able to share it. > > Examples are a special case. Small snippets are ok in expository > documentation > when you are explaining something, but it should be kept short. Complete > examples > are source code like any other, but more heavily commented and designed to > illustrate > a point. Link to examples, refer to them, but do not include them > wholesale in the API or > expository docs. And for Pete's sake, please do not syntax highlight > examples in > the documentation. There are endless ways to highlight, and if it isn't > colored the way > _you_ are used to then it's confusing. There's a reason they don't do this > in printed > manuals, beyond printing costs. > I guess that's a matter of taste. I find it much harder to read black on white code than hilighted code, even if the colors are completely off from what I'm used to :) No need to argue here, we'll just see how things go :) > > There's been some talk on the thread of doc metrics, tracking which docs > suck worst and > things like that. I say we already have a mechanism for doing that. WRITE > A BUG! Yes, > you can submit a bug for lacking or sub-par documentation. Someone might > even come > along and fix it! At the moment there is exactly 1 bug in Phab with the > word "documentation" > in it. That's no way to attract folks who want to contribute > documentation. > > I am not sold on the value of "discussions" associated with the > documentation. Can anyone > point to one that works well? I understand the desire to retain this kind > of informal information > somewhere, but I don't think it belongs with the docs. Phab has a Ponder > module? > I didn't even know about it... There's currently one question there, answered. Maybe it would need more visibility? It's not a standard app. Same for Diviner. Phab has some problems related to authentication. Unregistered users see basically none of the content that's on Phab. It could probably be half solved by setting the default visibility for everything to "public". We already had such trouble with the wiki visibility. As for commenting on documentation directly, the idea comes from the PHP docs: http://php.net/docs.php And also seeing how good StackOverflow works. Rating people who answer and answers themselves is how they filter out quality content. Something like that would be good, and Ponder doesn't seem to expose this very much (only individual answers can be rated, right?). > I took some time to look at Diviner today, to see how close it is to being > what we need for docs. > Structure is done with JSON files (*.book). Source files (*.diviner) are > written in plain old > markdown with a few @-tags thrown in for spice. It can generate API docs > from commented > source, but it currently only understands PHP. We'd have to fork or get > upstream to write an > "atomizer" (their term) that understands our stuff. > One great thing about gollum was how damn easy it was to test it. In just a minute the gem was installed and gollum running on my local machine. This means it's extremely simple to test the doc locally. I don't know if Phab can provide this kind of convenience. > > I really like the idea of having docs in Phab, but I have no idea how much > work it would be to > get it to work right. I will play around with it this weekend and see > what's possible. > The best for API docs would be if we could generate markdown from headers > and import that > to Diviner. > Please let us know! :) > > As others have said, for the bindings problem, I think each binding should > have its own > API reference and examples. One set of expository docs can serve for all. > > I agree that we should dump Doxygen. Sometimes the C macros confuse it. > > Ok, enough for now. I'll be back tomorrow. > Thanks. > > On Thu, Nov 6, 2014 at 4:15 PM, Carsten Haitzler <ras...@rasterman.com> > wrote: > > > On Thu, 6 Nov 2014 20:38:34 -0200 Felipe Magno de Almeida > > <felipe.m.alme...@gmail.com> said: > > > > > On Thu, Nov 6, 2014 at 5:09 AM, Carsten Haitzler <ras...@rasterman.com > > > > wrote: > > > > i thought i'd start this here for a wide audience. > > > > > > > > documentation for efl. it's rather horrible. and yesterday it dawned > on > > > > me... > > > > > > Hello raster, > > > > > > > this is a start - what do people have to add/say? > > > > > > > > do you have something ... better? can you improve the above? > > > > > > I'm going to say what I think is plausible solution to the > > > documentation problem we have today in EFL and Elementary. I don't > > > think it is better, but I think it is doable and is going to help the > > > project get users sooner rather than later. > > > > > > First of all, documentation was already problematic, but Eolian surely > > > made it much worse. It made it worse because it made EFL more usable > > > in contexts where it was not, but neither documentation nor tools > > > accompanied this widening of the EFL's horizont. > > > > > > I think we can still leverage on the current tools to create at least > > > good enough documentation, which we're still far away. If we can make > > > people *wink* *wink* work on Eolian to allow documentation from > > > multiple languages, by, e.g., tagging paragraphs per programming > > > language, we can generate doxygen, jsdoc, for each language. > > > > have you run "make doc" on efl lately? it takes longer than efl does to > > compile. a full "from scratch" compile. (actually it segfaults on arch - > i > > can't > > build docs at all .. after 30seconds). elementary is worse. by a massive > > margin. it's at the point where the feedback cycle is useless. seeing the > > results of what you fixed takes forever. its totally discouraging. i > think > > we > > just need to dump doxygen entirely as this is a major factor stopping > > people > > from doing anything. i look at it and go "shit - well there goes my day > > and i > > won't get a lot done" so i find something more productive to do. > > > > > I like the idea of adding a space for comments and discussions and > > > this can be added to generated documentation with not that much > > > effort. For doxygen, at least, we can generate XML and use XSLT -> > > > DocBook to generate very high quality documentation that can be very > > > well integrated through links (for example to show documentation to > > > other languages as well). > > > > > > I don't think we should, not yet at least, move our documentation > > > outside our code base in EFL. And the reason is that this is too huge > > > a task and requires EFL maintaining and developing a Web application. > > > If we're already lacking people to just write documentation how can we > > > expect to do that? > > > > thats why i was mentioning gollum - w don't maintain it. just a git repo > > with > > markdown. it has a web front-end ad a git "api" to mess with it. :) > > > > > I think it is useful to create a tool to analyze our documentation, so > > > we can spot easily where documentation is not being linked correctly > > > and where documentation is laking the most. This could even be added > > > to Stefan's weekly news and could even be considered for the 4 weeks > > > stabilizing period depending on how much a feature is lacking in > > > documentation. > > > > > > Also, the generators can improve documentation by using tagged > > > information from Eo files, such as ownership. It can warn the user > > > that one of the parameters, tagged with own, have to be freed by the > > > user for example. And this information is going to be correctly > > > sync'ed because otherwise most bindings would crash. > > > > > > Also, I agree that different languages should have separate > > > documentations because too much information distracts and discourages > > > the user. Specially when the information seems much more complicated > > > than what he is looking for. So a python developer going through > > > anything C or C++ related is going to run away pretty easy. > > > > so you're going to have to put this smarts into some eolian based tool as > > eolian now has to be taught to deal with structs, enums etc. anyway for > > js/lua/python etc. so if this has to go there to generate jsdoc ... and > > C/C++ > > is separate, then some other lua doc thing (don't even now) then some > > different > > python doc? why not just generate it all at once - generate simple > > markdown. :) > > keep the docs somewhere where they are community editable beyond just > core > > devs. if docs stay in .eo files the only peolpe able to work on them are > > those > > with core src commit access. this isn't working. there are many reasons, > > but > > it's failing now for years. and getting worse. > > > > > As for documentation that is exclusive to one language, such as > > > tutorials and examples. The binding maintainer can write a source code > > > in the target language with its documentation or a dox file. > > > > > > BTW, I'm assuming the bindings would be, someday, integrated to the > > > EFL tree. Which I think is a good thing. > > > > c++ are already. lua are already. others will depend on time/effort etc. > > but > > they can be. i am assuming any bindings we support in-tree will generate > > their > > own lang doc pages as above. :) > > > > > Kind regards, > > > > > > [snip] > > > > > > > -- > > > > ------------- Codito, ergo sum - "I code, therefore I am" > > -------------- > > > > The Rasterman (Carsten Haitzler) ras...@rasterman.com > > > > > > > > > > > > > > > ------------------------------------------------------------------------------ > > > > _______________________________________________ > > > > enlightenment-devel mailing list > > > > enlightenment-devel@lists.sourceforge.net > > > > https://lists.sourceforge.net/lists/listinfo/enlightenment-devel > > > > > > > > > -- > > > Felipe Magno de Almeida > > > > > > > > > ------------------------------------------------------------------------------ > > > _______________________________________________ > > > enlightenment-devel mailing list > > > enlightenment-devel@lists.sourceforge.net > > > https://lists.sourceforge.net/lists/listinfo/enlightenment-devel > > > > > > > > > -- > > ------------- Codito, ergo sum - "I code, therefore I am" -------------- > > The Rasterman (Carsten Haitzler) ras...@rasterman.com > > > > > > > > > ------------------------------------------------------------------------------ > > _______________________________________________ > > enlightenment-devel mailing list > > enlightenment-devel@lists.sourceforge.net > > https://lists.sourceforge.net/lists/listinfo/enlightenment-devel > > > > > > -- > -- Jeff Grimshaw > > ------------------------------------------------------------------------------ > _______________________________________________ > enlightenment-devel mailing list > enlightenment-devel@lists.sourceforge.net > https://lists.sourceforge.net/lists/listinfo/enlightenment-devel > > -- Jean-Philippe André ------------------------------------------------------------------------------ _______________________________________________ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
