On 08/06/15 11:30, Daniel Kolesa wrote: > On Mon, Jun 8, 2015 at 8:13 AM, Jean-Philippe André <j...@videolan.org> wrote: >> Hello, >> >> On Sat, Jun 6, 2015 at 1:19 AM, Tom Hacohen <t...@osg.samsung.com> wrote: >> >>> Hey, >>> >>> Daniel and I have been working recently on a new format for >>> documentation in Eo files. We want to use that in order to generate >>> basic documentation for methods/classes/parameters for use by IDEs and >>> in order to generate basic structure of documentation that will be >>> enhanced on the wiki with more usage tutorials, language specific >>> examples and etc. This means these documentations should be very short >>> and concise. No per method examples inline or anything like that. The >>> idea with the docs, as it is with the rest of Eolian is to be language >>> agnostic. >>> >>> Some things are done differently in different languages, but how the EFL >>> behaves remains the same. This means that most of the docs could be >>> written in a language-agnostic way with short tutorials per language >>> that translate the psuedocode examples into language specific examples. >>> Language specific tutorials are obviously still encouraged and will be >>> written with time. All of this will be done on the wiki, and not in .eo >>> files. >>> >>> We created a short wiki page that demonstrates the syntax we currently >>> use for docs in .eo files, you can see it here: >>> https://phab.enlightenment.org/w/eolian/docs/ >>> We use [[ as the starting delimiters and ]] as the ending delimiters. We >>> discourage the use of spaces between the delimiters and the text, so >>> this is a correct way of documenting a function: >>> [[This function does something]] >>> It's clear and clean, and will be even more clear with syntax highlighting. >>> >> The general idea of cleaning up the doc in the eo files sounds great. >> >> But I fail to understand why moving to a different syntax than what's >> currently there? >> >> - How are [[ ... ]] better than /*@ */ ? [[ ... ]] are just fine but this >> mean all the current eo files will have to be modified for something >> trivial. > They'd have to be modified either way, as the current docs in eo files > are poorly written and need to be mostly rewritten. The syntaxes of > what's written inside are not compatible. You never use doxygen tags > within the [[...]] docs; they'll be generated automatically by the > Eolian C generator. Anyway, they're better because you don't have to > deal with comment style formatting (for example, the convention is to > prefix each line in a comment with " * "). > >> Also the "no spaces preferred" rule does not seem to bring anything (except >> laziness in the parser :-P)... > There is a "no spaces preferred" rule because it looks better, but the > parser will strip whitespace nevertheless, there is no laziness > involved. > >> - What about @return tags? Are they just not needed if the doc is properly >> written? (hint: I'm not convinced as I often look for the RETURN part of a >> manpage or another library's doc) > They're not needed, as the @return is automatically inserted by the > Eolian C generator. For example generation for this: > https://git.enlightenment.org/core/efl.git/tree/src/tests/eolian/data/docs.eo > makes this kind of output: http://codepad.org/RIYt5yxi > >> - What about @since tags? > No @since tags atm. That stuff would probably be documented on the > wiki. The documentation in eo files is supposed to be bare, mostly for > autocompletion etc. Hmm, I would expect the since tag to be part of the bare docs in the eo files as well. They give an important hint if the API you are using is widely available (aka older).
regards Stefan Schmidt ------------------------------------------------------------------------------ _______________________________________________ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
