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. 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. 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 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. 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. 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. 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
