Some Eclipse Foundation services are deprecated, or will be soon. Please ensure you've read this important communication.

Bug 344452

Summary:	Epsilon sources documentation
Product:	[Modeling] Epsilon	Reporter:	Horacio Hoyos <arcanefoam>
Component:	Core	Assignee:	Dimitris Kolovos <dkolovos>
Status:	CLOSED NOT_ECLIPSE	QA Contact:
Severity:	enhancement
Priority:	P3	CC:	hugo.a.garcia, maarten.bezemer, proskorik
Version:	unspecified
Target Milestone:	---
Hardware:	PC
OS:	Windows 7
Whiteboard:

Description Horacio Hoyos

2011-05-02 09:27:37 EDT

I know keeping source code documented can be a task consuming task. However, while making my own stand alone helper for epsilon I felt as if I was in the dark trying to figure out what exactly did each class or function.  In the "How can I contribute to Epsilon?" section in the FAQs you express your willingness to accept bugs reports and fixes. Providing fixes or enhancements would be a tad easier if the code documentation was better.

Comment 1 Dimitris Kolovos

2014-06-29 09:00:26 EDT

Point taken. I'm not sure that this qualifies as a bug (i.e. I wouldn't know when we could close this as "resolved") so in the absence of a better solution, I'm inclined to close this as NOT_ECLIPSE.

Comment 2 Maarten Bezemer

2014-06-29 10:54:03 EDT

We (Epsilon contributers) could 'agree' to document each new method/class/field we add/modify. So the 'API documentation' slowly becomes (more) mature.
(As adding all documentation at once is an impossible (boring) task, I suppose)

Comment 3 Horacio Hoyos

2014-06-30 06:50:53 EDT

Wouldn't it be better to put it under "IN_PROGRESS"? Probably statistics wise it might look "bad" that a bug is under progress for a long time. But, IMHO, it gives the sense that at least some work is being done towards it. 

Another idea would be to plan a plugin/package based approach, in which we could split this bug into multiple ones (one for each plugin) and thus it would be more realistic to tackle them and eventually resolve each of them.

Comment 4 Dimitris Kolovos

2014-08-18 12:51:40 EDT

I agree that this is something we should aim for in the long run, but given that realistically this can never be closed as long as there's even one method with no javadoc in the Epsilon source code, it doesn't seem to be a good fit for the bugzilla lifecycle. Having said this, if there are any particular classes/methods for which you feel that javadoc is essential (e.g. due to their high complexity), please feel free to file a new enhancement request.