Bug 32213

Summary:	portage and emerge (and others) lack good code comments...
Product:	Portage Development	Reporter:	Radek Podgorny <radek>
Component:	Documentation	Assignee:	Portage team <dev-portage>
Status:	VERIFIED LATER
Severity:	normal
Priority:	High
Version:	unspecified
Hardware:	All
OS:	Linux
URL:	#gentoo-portage@irc.freenode.net
Whiteboard:
Package list:		Runtime testing required:	---

Description Radek Podgorny 2003-10-28 12:28:07 UTC

Hi,

seening all the current portage problems and feature requests, I decided to start hacking into portage BUT! how surprised I was when I found out that even an hour of studing the code isn't enough... :-( The code lacks comments so it's VERY hard for everyone outside the current portage-dev-group to understand the basic principles...

I think that if you created some kind of documentation or added the description to every function used and some explanations whenever necessary, the portage development will speed up a lot...

Thanks...
Radek

Comment 1 Radek Podgorny 2004-01-12 13:21:37 UTC

Anyone interested in this?

Comment 2 Radek Podgorny 2004-04-24 15:26:19 UTC

Still nothing?

Comment 3 Brian Harring (RETIRED) gentoo-dev

2004-07-16 02:03:36 UTC

Radek, don't spose you're up for taking a stab at this?

Comment 4 Alec Warner (RETIRED) archtester

2005-01-06 22:29:11 UTC

As a note, I am also trying to figure out portage.  Honestly, it's horribly commented, but IMHO it's not that bad.  Python is pretty good at letting the code document itself.  As far as the whole portage-layout deal, yeah there isn't any documentation for it.  From what I've heard, there won't be because most of the internals are being designed and rewritten for the new portage hotness.  The newer portage should have documentation.

*notes that he isn't a portage dev and his words are only what he heard from the gnomes on IRC*

Comment 5 Alec Warner (RETIRED) archtester

2005-01-17 20:47:07 UTC

Jstubbs says he was taking a stab at ripping out emerge code and commenting it in HEAD.

Comment 6 Brian Harring (RETIRED) gentoo-dev

2005-02-27 23:29:48 UTC

Marking this later.  the code needs better inline commentary- new code/modules are properly documented, the existing stuff (portage.py) is getting there slowly, too.
Emerge is another matter.  Anyone who is interested/want this, comment on the portage-dev ml if you're willing to help.

Help would be appreciated.

Comment 7 Marius Mauch (RETIRED) gentoo-dev

2007-01-11 12:27:50 UTC

Not much to have a bug about this.